> ## 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.

# anvil dev: Start the Live-Reload Development Server

> Run a live-reload dev server that watches your routes directory and hot-reloads TypeScript route files without a separate compilation step.

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

```bash theme={null}
anvil dev [options]
```

## Flags

<ParamField query="-r, --routes <dir>" type="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.
</ParamField>

<ParamField query="-p, --port <port>" type="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.
</ParamField>

<ParamField query="-H, --hostname <host>" type="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.
</ParamField>

## How it works

When you run `anvil dev`, the following happens:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Example output

```text theme={null}
  GET     /api/health
  POST    /api/chat
  GET     /api/users/[id]
[anvil] dev server listening on http://localhost:3000
```

After you edit a route file:

```text theme={null}
[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:

```text theme={null}
[anvil] reload failed: Cannot find module './missing-dep.js'
```

## Example: custom port and routes directory

```bash theme={null}
anvil dev --routes src/routes --port 4000 --hostname 127.0.0.1
```

<Note>
  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.
</Note>

<Tip>
  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`.
</Tip>