Getting Started

Welcome to the Agent-Native documentation!

Installation

Create a new project:

npx @agent-native/core create my-app

Project Structure

Every agent-native app follows the same convention:

my-app/
  app/             # React frontend (Vite SPA)
    App.tsx        # Entry point
    components/    # UI components
    lib/utils.ts   # cn() utility
  server/          # Nitro API server
    routes/        # File-based API routes (auto-discovered)
    plugins/       # Server plugins (startup logic)
    lib/           # Shared server modules
  shared/          # Isomorphic code (client & server)
  scripts/         # Agent-callable scripts
    run.ts         # Script dispatcher
  data/            # App data files (watched by SSE)

Vite Configuration

A single config file handles both client SPA and server build:

// vite.config.ts
import { defineConfig } from "@agent-native/core/vite";
export default defineConfig();

defineConfig() sets up React SWC, path aliases (@/ -> app/, @shared/ -> shared/), fs restrictions, and the Nitro server plugin (file-based API routing, server plugins, deploy-anywhere presets).

Nitro options

export default defineConfig({
  nitro: {
    preset: "vercel", // Deploy target (default: "node")
  },
});

TypeScript & Tailwind

// tsconfig.json
{ "extends": "@agent-native/core/tsconfig.base.json" }

// tailwind.config.ts
import type { Config } from "tailwindcss";
import preset from "@agent-native/core/tailwind";

export default {
  presets: [preset],
  content: ["./app/**/*.{ts,tsx}"],
} satisfies Config;

Subpath Exports

Import	Exports
@agent-native/core	Server, client, scripts: createServer, createFileWatcher, createSSEHandler, runScript, parseArgs, loadEnv, fail, agentChat, sendToAgentChat, useAgentChatGenerating, useFileWatcher, cn
@agent-native/core/vite	defineConfig()
@agent-native/core/tailwind	Tailwind preset (HSL colors, shadcn/ui tokens, animations)
@agent-native/core/adapters/sync	createFileSync, FileSync, FileSyncAdapter, FileRecord, FileChange

Architecture Principles

Files as database — All app state lives in files. Both UI and agent read/write the same files.
All AI through agent chat — No inline LLM calls. UI delegates to the AI via sendToAgentChat().
Scripts for agent ops — pnpm script <name> dispatches to callable script files.
Bidirectional SSE events — File watcher keeps UI in sync with agent changes in real-time.
Agent can update code — The agent modifies the app itself.
Deploy anywhere — Nitro presets let you deploy to Node.js, Vercel, Netlify, Cloudflare, AWS Lambda, Deno, and more.