# Recommended Tooling for Working with Builder.io Agent Native: Complete Developer Setup Guide > Discover recommended tooling for Builder.io Agent Native. Set up your development environment with pnpm, Node.js, CLI, oxfmt, and Vitest for seamless integration. - Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native) - Tags: getting-started - Published: 2026-07-18 --- **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`](https://github.com/BuilderIO/agent-native/blob/main/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: ```bash 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`](https://github.com/BuilderIO/agent-native/blob/main/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. ```bash pnpm dev ``` ### Production Builds For deployment to platforms like Netlify, Vercel, or Cloudflare, run the build script defined in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json): ```bash 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`](https://github.com/BuilderIO/agent-native/blob/main/.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: ```bash 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`](https://github.com/BuilderIO/agent-native/blob/main/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: ```bash pnpm dlx shadcn@latest add button ``` This creates files like [`components/ui/button.tsx`](https://github.com/BuilderIO/agent-native/blob/main/components/ui/button.tsx) that are fully compatible with the Tailwind 4 configuration defined in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/.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 ` command allows you to execute agent logic without the UI, useful for debugging or automation: ```bash pnpm action view-screen --id ``` ### Documentation Search For fast lookup of built-in framework documentation, use the docs-search action: ```bash 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`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/agent-native-docs/SKILL.md). ## Workspace Configuration ### Monorepo Setup The [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/.vscode/extensions.json) and [`.vscode/settings.json`](https://github.com/BuilderIO/agent-native/blob/main/.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`](https://github.com/BuilderIO/agent-native/blob/main/package.json) engines - **Scaffolding**: Bootstrap projects with `npx @agent-native/core@latest create ` - **Development**: Run `pnpm dev` (via [`scripts/dev-lazy.ts`](https://github.com/BuilderIO/agent-native/blob/main/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 ` 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`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) and specific `pnpm` commands in [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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 `. 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`](https://github.com/BuilderIO/agent-native/blob/main/.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.