Astro preview --background: Run a Built Site Without Holding the Terminal

Start and inspect the background preview#

From a project that has Astro 7.2.0 or a later release, build the site and start its preview server:

1
pnpm build
2
pnpm exec astro preview --background

The command returns after the preview is ready, so another command can run in the same terminal. Check whether the process is running and inspect its output with the companion commands:

1
pnpm exec astro preview status
2
pnpm exec astro preview logs
3
pnpm exec astro preview logs --follow

When the check is finished, stop the background process through Astro’s own lifecycle:

1
pnpm exec astro preview stop

Using the CLI for the lifecycle makes the state visible to a developer or coding agent. It also avoids leaving an old preview process running after the generated dist/ directory has changed.

Understand what preview is serving#

astro preview is a local check of the output produced by astro build. It does not watch source files or rebuild pages when you edit them. After changing content or configuration, run the build again before inspecting the new result:

1
pnpm build
2
pnpm exec astro preview --background

If the command is unknown, check the installed version rather than debugging the port first:

1
pnpm exec astro --version

The background preview lifecycle was added in Astro 7.2.0. A project pinned to an older Astro release should continue using its existing astro preview flow or upgrade in a deliberate dependency change. Do not copy a new CLI flag into a lockfile that still resolves an older binary.

Use the opt-out when automation should own the process#

Astro can automatically enable background mode when it detects an AI coding agent. If an automation runner expects astro preview to remain attached to its process group, disable that automatic behavior with the documented environment variable:

1
ASTRO_PREVIEW_BACKGROUND=0 pnpm exec astro preview

Use this opt-out when the surrounding tool already provides process supervision, timeout handling, or log collection. When you intentionally want a detached local preview, prefer the explicit --background command and keep the later status, logs, and stop calls in the same workflow.

Do not treat it as a production server#

Background mode is a convenience for checking a built site locally or in a short-lived verification job. It does not add an Astro adapter, a process supervisor, TLS termination, or deployment health checks. A static deployment still needs a web server or hosting platform to serve the generated files; the Astro static site with Caddy and Docker guide covers that separate runtime boundary.

For a CI check, keep the sequence explicit:

1. Install the lockfile’s dependencies.
2. Run the production build.
3. Start the preview only if the test needs HTTP responses.
4. Collect logs if a route check fails.
5. Stop the preview process in cleanup.

This ordering distinguishes a broken build from a preview-process problem. It also prevents a successful server start from hiding stale output in dist/.

FAQ#