# What Is the Purpose of the src Directory in Builder.io Agent Native?

> Discover the purpose of the src directory in Builder.io Agent Native. Learn how it organizes TypeScript source files for efficient development and production builds.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: internals
- Published: 2026-07-18

---

**The `src` directory in Builder.io Agent Native serves as the canonical location for TypeScript source files across the monorepo's packages, housing all implementation code, public APIs, internal logic, server-side handlers, and UI components that get compiled into production-ready JavaScript.**

The Builder.io Agent Native repository follows a strict monorepo architecture where every `@agent-native/*` package stores its implementation code under a dedicated `src` folder. This convention ensures that TypeScript source files remain isolated from build artifacts while providing a predictable location for developers to find executable, testable, and documentable code. Understanding the role of the `src` directory is essential for navigating the codebase and contributing to the Agent Native ecosystem.

## What Does the src Directory Contain in Builder.io Agent Native?

### TypeScript Implementation Files

Every `src` folder contains the raw TypeScript source that defines a package's functionality. Unlike the generated artifacts that appear in `dist` folders after compilation, the `src` directory holds the human-authored code that implements features ranging from React hooks to server-side routing logic.

### Public APIs and React Hooks

The `src` directory exposes the public interfaces that other packages consume. In [`packages/embedding/src/react.tsx`](https://github.com/BuilderIO/agent-native/blob/main/packages/embedding/src/react.tsx), the implementation provides React hooks that UI code imports to interact with the Agent Native state.

```tsx
// packages/embedding/src/react.tsx – Exposes a React hook that UI code can use
import { useActionQuery } from '@agent-native/core';
export function useAgentNative() {
  return useActionQuery('getAgentState');
}

```

### Server-Side Handlers

Server-side logic also resides within `src`, specifically in subdirectories like `src/server`. The scheduling package demonstrates this pattern by registering API routes within its source tree.

```ts
// packages/scheduling/src/server/index.ts – Registers server-side API routes
import { createRouter } from '@agent-native/core/server';
import { bookingService } from './booking-service';
export const router = createRouter()
  .get('/bookings', bookingService.list)
  .post('/bookings', bookingService.create);

```

## How the src Directory Integrates with the Build System

The repository uses `pnpm` scripts to compile files from each `src` tree into production JavaScript that ends up in the corresponding package's `dist` folder. This separation ensures that:

- **Source maps** reference the original TypeScript in `src` for debugging
- **Type declarations** generate from the source files to support downstream consumers
- **Published packages** only include the compiled output while maintaining source references

Keeping source code isolated in `src` makes the project modular, allowing each package to be built, tested, and published independently without cross-contamination from build artifacts.

## Key Examples of src Directory Usage Across Packages

### Creative Context Store Logic

The creative-context package centralizes its in-memory store implementation within `src`, exposing a clean interface for state management.

```ts
// packages/creative-context/src/store/index.ts – Core store logic for the creative-context feature
import { suggestions } from './suggestions';
import { sources } from './sources';
export const store = {
  suggestions,
  sources,
};

```

### VS Code Extension Implementation

Even non-standard packages follow the convention. The VS Code extension implements its bridge between the editor and Agent Native in [`packages/vscode-extension/src/extension.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/vscode-extension/src/extension.ts).

### Frame Server Implementation

The frame package hosts its Nitro server implementation in [`packages/frame/src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/frame/src/server.ts), demonstrating that server bootstrapping code also belongs in the `src` hierarchy.

| Package | Important `src` File | Purpose |
|---------|---------------------|---------|
| `embedding` | [`src/react.tsx`](https://github.com/BuilderIO/agent-native/blob/main/src/react.tsx) | Provides the main React entry point that applications import. |
| `scheduling` | [`src/server/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/src/server/index.ts) | Sets up the HTTP endpoints that power scheduling actions. |
| `creative-context` | [`src/store/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/src/store/index.ts) | Centralizes the in-memory store used by the creative-context engine. |
| `vscode-extension` | [`src/extension.ts`](https://github.com/BuilderIO/agent-native/blob/main/src/extension.ts) | Implements the VS Code extension bridge. |
| `frame` | [`src/server.ts`](https://github.com/BuilderIO/agent-native/blob/main/src/server.ts) | Hosts the Nitro server that powers the runtime environment. |

## Summary

- The `src` directory houses all TypeScript source files across the Builder.io Agent Native monorepo, establishing a consistent location for implementation code.
- Every package follows the convention of placing executable logic, React hooks, server routes, and utilities under its `src` folder.
- The build process compiles `src` contents into the `dist` directory, keeping source files separate from generated production artifacts.
- This structure makes the codebase modular, discoverable, and properly typed for both internal development and external consumption.

## Frequently Asked Questions

### What types of files are stored in the src directory of Builder.io Agent Native?

The `src` directory contains TypeScript implementation files including React components and hooks (like `useAgentNative` in [`packages/embedding/src/react.tsx`](https://github.com/BuilderIO/agent-native/blob/main/packages/embedding/src/react.tsx)), server-side route handlers (found in [`packages/scheduling/src/server/index.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/scheduling/src/server/index.ts)), state management logic, and utility functions. It specifically excludes compiled JavaScript, type declarations, and build artifacts, which reside in `dist` folders.

### How does the src directory differ from the dist folder in Builder.io Agent Native?

The `src` directory contains human-readable TypeScript source code that developers write and maintain, while the `dist` folder contains the machine-generated JavaScript output produced by the build system. According to the repository's `pnpm` build configuration, files in `src` get compiled and emitted to `dist` for production deployment, with `src` serving as the single source of truth for all package logic.

### Can I import files directly from the src directory in production?

No, production applications should import from the package's published exports rather than deep-linking into `src` directories. The `src` folder contains uncompiled TypeScript that requires transpilation. Production builds consume the compiled output from `dist` (or the package's main entry points) which provide the JavaScript bundles and type declarations derived from the original `src` files.

### Where should I add new features when contributing to Builder.io Agent Native?

New features should be added to the appropriate `src` directory within the relevant package. For React UI features, use `packages/embedding/src/`; for server-side API endpoints, add routes to `packages/scheduling/src/server/` or create analogous `src/server` structures in other packages. This ensures consistency with the monorepo's architectural standards and proper integration with the existing build pipeline.