Skip to main content
Run anvil dev to start a local development server that watches your routes directory and reloads route handlers the moment you save a file. Route modules are loaded on-the-fly so you write plain TypeScript — no compilation step required before your changes are live.

​
Usage

anvil dev [options]

​
Flags

​
-r, --routes <dir>
string
default:"server/routes"
Path to the directory Anvil scans for route files. Passed to the compiler’s manifest loader. Change this if your project uses a non-standard layout.
​
-p, --port <port>
number
default:"3000"
TCP port the HTTP server listens on. Useful when you need to run multiple Anvil apps side by side, or when port 3000 is already taken.
​
-H, --hostname <host>
string
Hostname to bind. Omit to bind to all interfaces (0.0.0.0). Set to 127.0.0.1 to restrict the server to localhost only.

​
How it works

When you run anvil dev, the following happens:
1

Scan and load routes

Anvil reads your routes directory, builds an in-memory manifest, and prints each discovered route with its HTTP method and URL pattern.
2

Start the HTTP server

An HTTP server starts listening on the configured port. The server is backed by a live reference to the current app instance.
3

Watch for file changes

Anvil watches the routes directory recursively. Any add, change, or unlink event triggers a debounced reload (100 ms debounce to coalesce rapid saves).
4

Hot-reload without restart

On each reload, Anvil clears the module cache for edited files and rebuilds the manifest. The HTTP server is not restarted — it begins serving the new route table immediately on the next request.

​
Example output

  GET     /api/health
  POST    /api/chat
  GET     /api/users/[id]
[anvil] dev server listening on http://localhost:3000
After you edit a route file: 
[anvil] routes reloaded
If a reload fails (for example, a TypeScript syntax error), the error is printed and the server continues to serve the last valid route table: 
[anvil] reload failed: Cannot find module './missing-dep.js'

​
Example: custom port and routes directory

anvil dev --routes src/routes --port 4000 --hostname 127.0.0.1
Each reload clears the module cache for the routes directory, ensuring edited files are always re-read from disk. Singletons shared across route files — such as a shared trace store — still resolve to one instance within a single build pass because the module cache is shared within that pass.
Add "dev": "anvil dev" to your package.json scripts so you can start the server with npm run dev without needing to prefix every invocation with npx.