Recommended Tooling for Working with Builder.io Agent Native: Complete Developer Setup Guide

The officially supported toolchain for Builder.io Agent Native includes pnpm (≥10), Node.js (≥22.22), the @agent-native/core CLI, oxfmt for formatting, and Vitest for testing.

Builder.io Agent Native is a TypeScript-first framework for building AI-driven applications. The repository enforces a tightly controlled development stack to ensure deterministic builds, end-to-end type safety, and seamless agent action integration. This guide covers every recommended tool, script, and configuration file you need to develop, test, and deploy Agent Native applications productively.

Core Development Stack

Package Manager and Runtime

pnpm (version 10 or higher) is the required package manager for all Agent Native projects. According to the package.json in the BuilderIO/agent-native repository, pnpm guarantees deterministic lock-files and workspace-aware script execution across the monorepo. The framework also requires Node.js ≥22.22, as declared in the engines field, to leverage recent V8 features and the latest TypeScript build of the core runtime.

Project Scaffolding

To bootstrap a new application, use the official CLI command referenced in the README quick-start guide:

npx @agent-native/core@latest create my-app
cd my-app

This command generates a complete project structure with the correct template, dependencies, and configuration files pre-configured for the Agent Native framework.

Development Workflow and CLI Commands

Running the Development Server

The pnpm dev command is the entry point for local development. This script executes scripts/dev-lazy.ts, which starts both the Vite-powered React frontend and the Nitro server in a single process. It provides hot-module replacement and live-sync for agent actions, allowing you to iterate on UI components and backend logic simultaneously.

pnpm dev

Production Builds

For deployment to platforms like Netlify, Vercel, or Cloudflare, run the build script defined in package.json:

pnpm build

This produces a production-ready Vite build for the client and a Nitro bundle for the server, optimized for edge deployment.

Type Safety and Linting

The repository provides dedicated scripts for type checking and formatting. Running pnpm typecheck (which uses the tsx runner) executes the TypeScript compiler across the entire monorepo to catch type errors before runtime.

For code style, the framework uses oxfmt and recommends the oxc VSCode extension. These tools enforce the repository's style guide—including single-quote strings, prohibition of any types, and consistent imports—and can auto-fix on save when configured via .vscode/settings.json.

Testing and Quality Assurance

Test Runner

The framework uses Vitest for unit, integration, and end-to-end testing. Execute the full test suite with:

pnpm test

Guard Scripts

Agent Native includes CI-only guard scripts that enforce security and data-access contracts. Commands like pnpm guard:no-drizzle-push and pnpm guard:no-unscoped-queries fail fast if unsafe patterns are detected. These scripts are defined in package.json (lines 50-73) and run automatically in continuous integration pipelines to prevent deployment of vulnerable code.

UI Component Development

shadcn UI Integration

For adding pre-built UI components that integrate with Tailwind CSS and the framework's design system, use the shadcn CLI:

pnpm dlx shadcn@latest add button

This creates files like components/ui/button.tsx that are fully compatible with the Tailwind 4 configuration defined in pnpm-workspace.yaml. You can also use info or docs subcommands to explore available components before installing them, as documented in .agents/skills/shadcn-ui/SKILL.md.

Agent-Specific Tooling

Framework Actions

Agent Native exposes a powerful CLI for running framework actions directly from the terminal. The pnpm action <name> command allows you to execute agent logic without the UI, useful for debugging or automation:

pnpm action view-screen --id <screen-id>

Documentation Search

For fast lookup of built-in framework documentation, use the docs-search action:

pnpm action docs-search --query "authentication"

This queries the version-matched documentation stored in node_modules/@agent-native/core/docs, as detailed in .agents/skills/agent-native-docs/SKILL.md.

Workspace Configuration

Monorepo Setup

The pnpm-workspace.yaml file defines workspace packages and pins catalog versions for shared dependencies like React 19 and Tailwind 4. This ensures consistency across packages when working with the Agent Native monorepo structure.

Editor Configuration

The repository includes .vscode/extensions.json and .vscode/settings.json to recommend the oxc formatter and configure TypeScript-native preview settings. These files ensure that all contributors use the same formatting rules and editor behavior, reducing noise in pull requests.

Summary

• Package management: Use pnpm ≥10 with Node.js ≥22.22 as specified in package.json engines
• Scaffolding: Bootstrap projects with npx @agent-native/core@latest create <app>
• Development: Run pnpm dev (via scripts/dev-lazy.ts) for unified frontend and Nitro server startup
• Code quality: Rely on pnpm typecheck for type safety and oxfmt/oxc for formatting
• Testing: Execute pnpm test for Vitest-based testing and pnpm guard:* scripts for security enforcement
• UI components: Add shadcn components via pnpm dlx shadcn@latest add
• Agent operations: Use pnpm action <name> for CLI-driven agent execution and pnpm action docs-search for documentation queries

Frequently Asked Questions

Can I use npm or yarn instead of pnpm?

No. The BuilderIO/agent-native repository assumes pnpm for all scripts, workspace resolution, and CI pipelines. The pnpm-workspace.yaml and specific pnpm commands in package.json make pnpm mandatory for correct dependency resolution and script execution.

What Node.js version is required?

The framework requires Node.js version 22.22 or higher, as declared in the engines field of package.json. This ensures compatibility with the modern V8 features and TypeScript build targets used by the core runtime.

How do I add new UI components to my Agent Native app?

Use the shadcn CLI command pnpm dlx shadcn@latest add <component-name>. This generates components in your components/ui/ directory that are pre-configured to work with Tailwind 4 and the Agent Native design system, as documented in the shadcn skill file.

Are custom linting tools supported?

While you can technically add custom linters, the repository enforces oxfmt through .vscode/settings.json and guard scripts. Deviating from the recommended oxc formatter may cause CI failures, as guard scripts like scripts/guard-no-unscoped-queries.mjs assume specific code patterns and formatting standards.

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