Dev server

The astro dev command runs a long-lived Vite development server with HMR. It lives at the intersection of three subsystems: core/dev/ (the orchestrator), vite-plugin-astro-server/ (the SSR middleware), and the larger Vite plugin stack.

Purpose

Boot a Vite server with all of Astro's plugins, hold it open, render every request through RenderContext, and surface errors via the dev overlay.

Key files

File	Purpose
packages/astro/src/cli/dev/index.ts	CLI entry, parses flags, resolves config.
packages/astro/src/core/dev/dev.ts	Public dev() JS API, prints the banner, attaches content listeners, handles ctrl-C.
packages/astro/src/core/dev/container.ts	Vite + Astro Container lifecycle.
packages/astro/src/core/dev/restart.ts	createContainerWithAutomaticRestart — watches config changes and restarts cleanly.
packages/astro/src/core/dev/update-check.ts	Throttled npm version check with a MAX_PATCH_DISTANCE.
packages/astro/src/vite-plugin-astro-server/	The Vite plugin that hooks req → RenderContext per request.
packages/astro/src/vite-plugin-environment/	Pre-bundles dependencies reachable through .astro files.
packages/astro/src/core/create-vite.ts	Assembles the Vite config and plugin order.

Lifecycle

sequenceDiagram
    participant CLI
    participant dev as core/dev/dev.ts
    participant container as core/dev/container.ts
    participant restart as core/dev/restart.ts
    participant vite as Vite server
    participant plugins as vite-plugin-astro-server

    CLI->>dev: dev({ flags })
    dev->>dev: warnIfVite8 / shouldCheckForUpdates
    dev->>restart: createContainerWithAutomaticRestart
    restart->>container: createContainer(config)
    container->>vite: createServer(viteConfig)
    vite->>plugins: register
    container->>plugins: attach manifest + Pipeline
    container-->>dev: { handle, watcher, address }
    dev->>vite: listen()
    Note over vite,plugins: Per request, plugins build a RenderContext and run middleware/render
    CLI->>dev: SIGINT
    dev->>container: stop()

Per-request flow

graph LR
    A[Vite dev server] -->|HTTP req| B[vite-plugin-astro-server middleware]
    B --> C[Build/cache DevPipeline]
    C --> D[Match route]
    D --> E[Build RenderContext]
    E --> F[Run middleware chain]
    F --> G[Render page or endpoint]
    G --> H[Stream Response]
    H --> A

The DevPipeline is reused across requests; only the per-request RenderContext is fresh. See systems / render context.

Restart-on-config-change

packages/astro/src/core/dev/restart.ts wraps the container with a watcher on the resolved config files (astro.config.{mjs,ts,js,cjs,mts}, integrations' config files, env files). When any of them change:

1. The current Vite server shuts down.
2. The config is re-resolved.
3. A new container is spun up at the same port.
4. Open browser tabs reconnect via Vite's HMR.

This gives the impression of "live config reload" without any in-place mutation.

Update notifications

update-check.ts checks npm for a newer Astro version once per dev session, throttled by:

• shouldCheckForUpdates() — respects telemetry opt-out and a 24h cache.
• MAX_PATCH_DISTANCE — only nags about patch updates within a small window to avoid spamming users on long-running dev servers.

If a new version is available, the user sees a one-line "new version available" message after the dev server's address banner.

Vite 8 warning

warnIfVite8() checks the resolved vite/package.json and prints a warning if the user is on Vite 8 (Astro pins to Vite 7 via the root pnpm.overrides). This is a transitional safety net.

Dev toolbar

The dev toolbar UI is loaded by packages/astro/src/runtime/client/dev-toolbar/ and registered as a Vite virtual module. The server-side glue is in packages/astro/src/toolbar/ and packages/astro/src/vite-plugin-overlay/. See features / dev toolbar for capabilities.

Entry points for modification

• Add a dev-only feature: write a Vite plugin that hooks configureServer(), register it from a new file under src/vite-plugin-*/, and add it to the plugin list in core/create-vite.ts.
• Change the dev banner: edit src/core/messages/runtime.ts.
• Tune update-check behavior: src/core/dev/update-check.ts.

Related pages

• systems / render context
• systems / Vite plugins
• reference / Vite dep optimizer — single most common dev-only failure mode.
• features / dev toolbar