Development Environment Configuration Files in Builder.io Agent Native

Builder.io Agent Native provides a comprehensive suite of development environment configuration files organized by purpose—covering TypeScript compilation, Vite bundling, testing frameworks, and environment variable templates—scoped across the root, individual packages, and template applications.

The BuilderIO/agent-native monorepo relies on these structured configuration files to ensure consistent code style, reproducible builds, and standardized local development workflows across its multiple packages and templates. Understanding where these files live and how they interact is essential for contributors setting up the repository or extending its functionality.

Core Repository-Wide Configuration Files

Editor Settings with .editorconfig

The repository root contains an .editorconfig file that enforces consistent editor settings—including indentation style, character set, and line endings—across all contributors' IDEs. This file is automatically respected by modern code editors, ensuring uniform formatting without requiring additional tooling.

TypeScript Base Configuration

The packages/core directory serves as the foundation for TypeScript settings across the workspace:

• packages/core/tsconfig.base.json – Defines the baseline compiler options shared by every package in the monorepo. All other tsconfig.json files extend this base configuration.
• packages/core/tsconfig.cli.json – Contains TypeScript settings specific to CLI-only scripts, such as migration utilities or build tools.
• packages/core/tsconfig.json – The default TypeScript configuration for the core package itself, which other dependent packages import and extend.

Build and Test Configuration Files

Vite Configuration Structure

Builder.io Agent Native uses Vite for development server orchestration and production bundling. The configuration follows a hierarchical pattern:

• Root vite.config.ts – The base Vite configuration that governs the root workspace-wide development server and shared build settings.
• Per-Package vite.config.ts – Individual packages like packages/desktop-app and packages/agent-chrome-extension contain their own vite.config.ts files that override or extend the root configuration to tailor bundling behavior for specific runtime targets.

Testing Framework Configuration

The repository supports both unit and end-to-end testing through distinct configuration files:

• Vitest Configuration (vitest.config.ts) – Located in the root, individual packages, and templates (such as templates/tasks/vitest.config.ts), these files define unit test globals, coverage thresholds, and TypeScript integration for the Vitest test runner.
• Playwright Configuration (playwright.config.ts) – Found primarily in template directories like templates/tasks/playwright.config.ts, this file configures the Playwright E2E test runner with base URLs (typically http://localhost:5173), browser settings, and test directory paths.

Environment Variables and Local Development Setup

.env.example Templates

Rather than committing sensitive credentials, the repository provides .env.example files that act as checklists for required environment variables. Each template and the core workspace include these templates:

• templates/tasks/.env.example – Documents API keys for task providers, database URLs, and feature-flag toggles.
• templates/design/.env.example – Lists design-service credentials and synchronization endpoints.
• templates/calendar/.env.example – Specifies calendar API tokens and OAuth client IDs.
• templates/analytics/.env.example – Contains analytics service keys and data-warehouse URLs.
• templates/dispatch/.env.example – Outlines dispatch-service secrets and webhook URLs.
• packages/core/src/templates/workspace-root/.env.example – Defines global variables such as database connection strings and JWT secrets.
• packages/core/src/templates/default/.env.example – Provides default development-mode environment variables.

Developers copy these examples to a local .env file (which is gitignored) and populate them with actual values to configure their local runtime environment.

Database and Synchronization Configuration

Templates that require data persistence include additional configuration files:

• drizzle.config.ts – Located in templates like templates/calendar/drizzle.config.ts, this file configures the Drizzle ORM database connection for local development.
• sync-config.json – Found in template data directories (e.g., templates/calendar/data/sync-config.json), this file defines data-synchronization behavior for background sync jobs and local database setup.

Practical Development Workflows

Installing Dependencies and Starting the Development Server

To bootstrap a local development environment for a specific template, run the following commands:

# Install all workspace dependencies

pnpm install

# Copy the example environment file for your chosen template

cp templates/tasks/.env.example .env

# Edit .env with your specific values (non-secret configuration)

# Start the Vite development server for the tasks template

pnpm --filter tasks dev

The pnpm --filter <package-name> command scopes execution to the specific package or template, ensuring only relevant dependencies and configurations are loaded.

Running Unit Tests

Execute the Vitest test suites using the configured vitest.config.ts files:

# Run all unit tests across the monorepo

pnpm test

# Run tests for a specific template only

pnpm --filter analytics test

Each template's Vitest configuration automatically inherits TypeScript settings from its local tsconfig.json, ensuring type-checking consistency during test execution.

Running End-to-End Tests

Launch Playwright tests using the configuration defined in templates/tasks/playwright.config.ts:

# Launch Playwright in UI mode for interactive debugging

pnpm test:e2e

# Execute tests in headless mode for CI pipelines

pnpm test:e2e --headless

Accessing Environment Variables in Application Code

Once the .env file is populated, access variables in TypeScript files as shown below:

// src/config.ts
export const API_KEY = process.env.NEXT_PUBLIC_API_KEY!;
export const DATABASE_URL = process.env.DATABASE_URL!;

Vite's built-in dotenv support automatically loads these variables when running the development server or building for production.

Summary

• Builder.io Agent Native organizes development environment configuration files hierarchically, with root-level settings in .editorconfig and packages/core/tsconfig.base.json cascading down to individual packages and templates.
• Vite configurations exist at both the root (vite.config.ts) and per-package levels (e.g., packages/desktop-app/vite.config.ts) to handle bundling and development server customization.
• Testing is configured through vitest.config.ts for unit tests and playwright.config.ts for end-to-end tests, with each template maintaining its own test runner settings.
• Environment variable templates (.env.example) are distributed across all templates and core packages, providing secure documentation of required configuration without exposing secrets.
• Database and ORM configuration is handled via drizzle.config.ts and sync-config.json files within individual templates that require data persistence.

Frequently Asked Questions

Where are the TypeScript configuration files located in Builder.io Agent Native?

The base TypeScript configuration resides in packages/core/tsconfig.base.json, which is extended by package-specific tsconfig.json files throughout the repository. Additional specialized configurations include packages/core/tsconfig.cli.json for command-line scripts and individual tsconfig.json files in each template directory (such as templates/tasks/tsconfig.json).

How do I configure local environment variables for development?

Copy the appropriate .env.example file from your target template (e.g., templates/tasks/.env.example) to a new .env file in the same directory, then populate it with your specific API keys and connection strings. These example files list all required variables without containing actual secrets, making them safe to commit to version control as templates.

What testing configuration files does the repository use?

The repository uses vitest.config.ts for unit test configuration across packages and templates, defining test globals and coverage settings. For end-to-end testing, playwright.config.ts files (primarily located in template directories like templates/tasks/) configure browser automation, base URLs, and test timeouts.

How is the build system configured for different packages?

Each package uses Vite configured through hierarchical vite.config.ts files. The root configuration provides baseline settings, while individual packages like packages/desktop-app override these in their own vite.config.ts files to accommodate specific bundling requirements, such as Electron-specific settings for desktop applications or extension manifests for browser add-ons.

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