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

Anvil is distributed as a single npm package, published as anvil-sdk — the anvil name on npm belongs to an unrelated package, so the install command uses anvil-sdk while every CLI command you run stays anvil (anvil dev, anvil build, and so on). This page covers everything needed to go from an empty directory to a correctly configured, running Anvil project.

Requirements

Node.js ≥ 20 — Anvil relies on the native Request, Response, Headers, and ReadableStream APIs that ship with Node 20; there’s no polyfill layer.
An 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; examples below cover all three.

Install the package

npm install anvil-sdk zod

yarn add anvil-sdk zod

pnpm add anvil-sdk zod

zod is a direct dependency of your route and tool schemas — install it alongside Anvil. Anvil re-exports the pieces of Zod it needs internally, but you write your own z.object(...) calls, so it must be present in your own dependencies.

The package name is anvil-sdk, but every command you run is still anvil — npx anvil dev, npx anvil build, and so on. Only the string you pass to npm install/yarn add/pnpm add uses the -js suffix.

Scaffold with `anvil init`

The fastest path to a working project is anvil init — it writes package.json, tsconfig.json, .gitignore, and a starter route or two, so you don’t hand-assemble the project structure yourself:

npx anvil init

Without any flags, and when stdin is a TTY, it prompts you to pick a starting point:

basic
mcp
agent

A minimal REST API — one static route (GET /) and one dynamic route (GET /users/[id]). The default template; good for plain HTTP APIs with no AI surface.

npx anvil init --template basic

The same two routes, with the dynamic route also exposed as an MCP tool (meta.mcp.expose), plus a standalone tool file under server/tools/ that has no backing HTTP route at all.

npx anvil init --template mcp

A streaming agent route at POST /chat, wired to MockDriver so it runs immediately with no API key — swap in AnthropicDriver, OpenAIDriver, or GeminiDriver when you’re ready for a real model.

npx anvil init --template agent

Pass -y to accept the basic default without prompting — useful in CI or scripts:

npx anvil init -y

anvil init never overwrites a file that already exists — running it in a directory that already has a package.json merges in the dev/build/start/lint scripts and the anvil-sdk/zod dependencies (without clobbering versions you’ve already pinned) instead of starting over. Re-running it is always safe; it reports what it wrote and what it skipped:

  ✎ update  package.json
  – skip    server/routes/get.ts (already exists)
  ✔ create  server/routes/users/[id]/get.ts

2 file(s) written, 1 skipped.

It only writes files — it doesn’t run npm install for you and doesn’t assume a package manager, so run that yourself afterward:

npm install
npm run dev

Full anvil init reference

Every flag, what gets merged versus created, and non-interactive usage for CI.

Configure package.json by hand

If you’d rather not use anvil init, add "type": "module" yourself and wire up the scripts:

package.json

{
  "name": "my-api",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "anvil dev",
    "build": "anvil build",
    "start": "anvil start",
    "lint": "anvil lint"
  },
  "dependencies": {
    "anvil-sdk": "latest",
    "zod": "latest"
  }
}

If you omit "type": "module", Node treats your files as CommonJS and import ... from 'anvil-sdk' fails with a syntax error at the first import/export statement. ESM is required — there is no CommonJS build.

Project structure

Route handlers live under server/routes/; everything else is up to you:

my-api/
├── server/
│   ├── routes/
│   │   ├── get.ts              → GET /
│   │   └── users/
│   │       ├── get.ts          → GET /users
│   │       └── [id]/
│   │           └── get.ts      → GET /users/:id
│   └── tools/                  → standalone MCP tools (no HTTP route)
├── package.json
├── tsconfig.json
└── .gitignore

A minimal tsconfig.json — the one anvil init writes:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true
  }
}

moduleResolution: "bundler" matches how anvil dev/anvil build resolve subpath exports like anvil-sdk/agent and anvil-sdk/llm — using "node16" or "nodenext" instead still works, but "bundler" gives the cleanest editor experience for these deep imports.

Optional peer dependencies

Core routing and middleware need nothing beyond anvil-sdk and zod. AI provider drivers and persistence adapters are optional peer dependencies, loaded lazily — install only what you actually use, and pure-REST projects stay lean.

Anthropic (Claude)

Required to use AnthropicDriver from anvil-sdk/llm in an agent route or LlmClient.

npm install @anthropic-ai/sdk

OpenAI (GPT / o-series)

Required to use OpenAIDriver from anvil-sdk/llm.

npm install openai

Google Gemini

Required to use GeminiDriver from anvil-sdk/llm.

npm install @google/generative-ai

SQLite persistence

Required for SqliteStateStore, SqliteTraceStore, or SqliteVectorStore — persists traces, checkpoints, memory, and vectors across restarts instead of losing them on process exit.

npm install better-sqlite3

Using a driver or store whose peer dependency isn’t installed throws a clear error at the call site naming the missing package and the in-memory alternative you can fall back to — it never fails silently.

CLI commands reference

Once installed, the anvil binary is available in node_modules/.bin/. Run it through your package manager’s script runner (npm run dev, or npx anvil dev directly):

Command	What it does
`anvil init`	Scaffolds `package.json`, `tsconfig.json`, `.gitignore`, and starter routes from a template (`basic`, `mcp`, or `agent`) — merges into an existing project instead of overwriting
`anvil dev`	Starts the dev server on port 3000 with watch mode; TypeScript routes load on the fly via `jiti`, no separate compile step
`anvil build`	Scans `server/routes/`, generates `.gen/routes.ts`, and bundles `dist/server.mjs` for production; fails hard on route conflicts
`anvil start`	Runs the production bundle. Requires `anvil build` first
`anvil lint`	Validates every route: `paramsSchema` keys against folder params, MCP-exposed schemas against lossless JSON Schema conversion. Add `--strict` to fail on warnings too
`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` file against an agent route — deterministic assertions plus LLM-as-judge — and exits non-zero on any failing case
`anvil replay <traceId>`	Re-runs a captured agent trace with mocked model responses and recorded tool outputs — no live model calls, useful for debugging a production failure locally

anvil CLI overview

Deeper reference for every command, including flags not covered above.

Verify the installation

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

server/routes/get.ts

export default function handler() {
  return { status: 'ok' };
}

npm run dev

[anvil] dev server listening on http://localhost:3000

curl http://localhost:3000/

{ "status": "ok" }

If you see that JSON response, the installation is complete and the dev server is correctly loading your route files.

Next steps

Quickstart

Build a validated dynamic route, expose it as an MCP tool, and add a streaming agent — one walkthrough.

anvil init

Every template, flag, and file it writes — including how it merges into an existing project.

File-Based Routing

The full routing convention: verbs, groups, catch-alls, and the generated route manifest.

MCP Overview

Expose routes and standalone tools as MCP tools over stdio or Streamable HTTP.

Get Started

Routing

MCP & Tools

Agent Routes

Observability

Safety & Durability

Memory & RAG

Background Tasks

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

Requirements

Install the package

Scaffold with `anvil init`

Full anvil init reference

Configure package.json by hand

Project structure

Optional peer dependencies

Anthropic (Claude)

OpenAI (GPT / o-series)

Google Gemini

SQLite persistence

CLI commands reference

anvil CLI overview

Verify the installation

Next steps

Quickstart

anvil init

File-Based Routing

MCP Overview

​Requirements

​Install the package

​Scaffold with anvil init

Full anvil init reference

​Configure package.json by hand

​Project structure

​Optional peer dependencies

Anthropic (Claude)

OpenAI (GPT / o-series)

Google Gemini

SQLite persistence

​CLI commands reference

anvil CLI overview

​Verify the installation

​Next steps

Quickstart

anvil init

File-Based Routing

MCP Overview

Requirements

Install the package

Scaffold with `anvil init`

Configure package.json by hand

Project structure

Optional peer dependencies

CLI commands reference

Verify the installation

Next steps