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

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, the implementation provides React hooks that UI code imports to interact with the Agent Native state.

// 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.

// 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.

// 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.

Frame Server Implementation

The frame package hosts its Nitro server implementation in 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	Provides the main React entry point that applications import.
scheduling	src/server/index.ts	Sets up the HTTP endpoints that power scheduling actions.
creative-context	src/store/index.ts	Centralizes the in-memory store used by the creative-context engine.
vscode-extension	src/extension.ts	Implements the VS Code extension bridge.
frame	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), server-side route handlers (found in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}