> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Anvil JS: Setup, ESM Config, and Peer Deps

> Install Anvil JS via npm, yarn, or pnpm, configure your ESM project, add optional AI provider peer deps, and set up your package.json scripts.

Anvil is distributed as a single npm package. This page covers everything you need to go from a blank directory to a correctly configured Anvil project.

## Requirements

Before installing, make sure your environment meets these requirements:

* **Node.js ≥ 20** — Anvil relies on the native `Request`, `Response`, `Headers`, and `ReadableStream` APIs that ship with Node 20.
* **ESM project** — Anvil is ESM-only. Your `package.json` must declare `"type": "module"`.
* **npm, yarn, or pnpm** — any of the three major package managers work.

## Install the package

<CodeGroup>
  ```bash npm theme={null}
  npm install anvil zod
  ```

  ```bash yarn theme={null}
  yarn add anvil zod
  ```

  ```bash pnpm theme={null}
  pnpm add anvil zod
  ```
</CodeGroup>

`zod` is a direct dependency of your route and tool schemas — install it alongside Anvil.

## Configure package.json

Add `"type": "module"` to enable ESM, then add the Anvil CLI commands as scripts:

```json package.json theme={null}
{
  "name": "my-api",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "anvil dev",
    "build": "anvil build",
    "start": "anvil start",
    "lint": "anvil lint"
  },
  "dependencies": {
    "anvil": "latest",
    "zod": "latest"
  }
}
```

<Note>
  If you omit `"type": "module"`, Node treats your files as CommonJS and imports from `anvil` fail with a syntax error. ESM is required.
</Note>

## Minimal project structure

Anvil expects your route handlers to live under `server/routes/`. Everything else is up to you.

```text theme={null}
my-api/
├── server/
│   └── routes/
│       └── get.ts       ← GET / (your first route)
├── package.json
└── tsconfig.json        ← optional, but recommended
```

A minimal `tsconfig.json` for an Anvil project:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true
  }
}
```

## Optional peer dependencies

Anvil's core routing and middleware work with no extra packages. The AI provider integrations and persistence adapters are **optional peer dependencies**, loaded lazily — install only what you use.

<CardGroup cols={2}>
  <Card title="Anthropic (Claude)" icon="brain">
    Required if you use `AnthropicDriver` in an agent route or LLM client.

    ```bash theme={null}
    npm install @anthropic-ai/sdk
    ```
  </Card>

  <Card title="OpenAI (GPT / o-series)" icon="sparkles">
    Required if you use `OpenAIDriver`.

    ```bash theme={null}
    npm install openai
    ```
  </Card>

  <Card title="Google Gemini" icon="google">
    Required if you use `GeminiDriver`.

    ```bash theme={null}
    npm install @google/generative-ai
    ```
  </Card>

  <Card title="SQLite persistence" icon="database">
    Required for `SqliteStateStore`, `SqliteTraceStore`, or `SqliteVectorStore` — persistent traces, checkpoints, memory, and vectors across restarts.

    ```bash theme={null}
    npm install better-sqlite3
    ```
  </Card>
</CardGroup>

<Note>
  If you try to use a driver or store whose peer dependency is not installed, Anvil throws a clear error at the call site pointing you to the missing package and the in-memory alternative — it will not silently fail.
</Note>

## CLI commands reference

Once installed, the `anvil` binary is available in your `node_modules/.bin/`. Running it through `npm run` (or your package manager equivalent) is the recommended approach.

| Command                  | What it does                                                                                                                                                           |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `anvil dev`              | Starts the dev server on port 3000 with watch mode. TypeScript routes are loaded on the fly via `jiti`.                                                                |
| `anvil build`            | Scans `server/routes/`, generates `.gen/routes.ts`, and bundles `dist/server.mjs` for production.                                                                      |
| `anvil start`            | Runs the production bundle. Requires `anvil build` first.                                                                                                              |
| `anvil lint`             | Validates all routes: checks `paramsSchema` keys match folder params, verifies MCP-exposed schemas convert cleanly to JSON Schema. Add `--strict` to fail on warnings. |
| `anvil mcp`              | Serves MCP-exposed routes and `server/tools/` over Streamable HTTP on port 3100. Pass `--stdio` for Claude Desktop and similar local clients.                          |
| `anvil eval <file>`      | Runs a `defineEvalSuite` test file against an agent route; exits non-zero if any case fails.                                                                           |
| `anvil replay <traceId>` | Re-runs a captured agent trace with mocked model responses and recorded tool outputs — no live model calls.                                                            |

## Verify the installation

Create a minimal route and start the dev server to confirm everything is working:

```ts server/routes/get.ts theme={null}
export default function handler() {
  return { status: 'ok' };
}
```

```bash theme={null}
npm run dev
# [anvil] dev server listening on http://localhost:3000
```

```bash theme={null}
curl http://localhost:3000/
# {"status":"ok"}
```

If you see the JSON response, your installation is complete.

## Scaffold instead of hand-writing

Once installed, `npx anvil init` writes `package.json` (scripts + dependencies), `tsconfig.json`, `.gitignore`, and a starter route for you — pick a basic API, MCP server, or agent route template. See [anvil init](/cli/init).

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build a route, expose it as an MCP tool, and add a streaming agent — in one walkthrough.
  </Card>

  <Card title="File-Based Routing" icon="folder-tree" href="/routing/file-based-routing">
    The full routing convention: verbs, groups, catch-alls, and the route manifest.
  </Card>
</CardGroup>