From 294dda377fa848674f43ee10773667f55339cfb0 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 4 Aug 2026 08:33:03 -0400 Subject: [PATCH 1/5] Document astro preview --background --- src/content/docs/en/guides/build-with-ai.mdx | 14 +++++++ .../docs/en/reference/cli-reference.mdx | 42 +++++++++++++++++++ 2 files changed, 56 insertions(+) diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx index 5763d582929f9..5df83e0157080 100644 --- a/src/content/docs/en/guides/build-with-ai.mdx +++ b/src/content/docs/en/guides/build-with-ai.mdx @@ -376,6 +376,20 @@ ASTRO_DEV_BACKGROUND=0 astro dev See the [CLI reference](/en/reference/cli-reference/#astro-dev) for the full list of `astro dev` flags and subcommands. +### Preview servers + +

+ +The `astro preview` command uses the same background mode as `astro dev`. When an AI coding agent is detected, or when you pass the [`--background` flag](/en/reference/cli-reference/#--background-1), the preview server starts as a detached background process and writes a lock file (`.astro/preview.json`) recording its URL, port, and PID. + +To opt out of automatic background mode, set the `ASTRO_PREVIEW_BACKGROUND` environment variable before running `astro preview`: + +```shell +ASTRO_PREVIEW_BACKGROUND=0 astro preview +``` + +See the [CLI reference](/en/reference/cli-reference/#astro-preview) for the full list of `astro preview` flags and subcommands. + ### Health endpoint The dev server exposes a `/_astro/status` endpoint that returns `{"ok": true}` as JSON. This allows agents and other tools to check programmatically whether the dev server is ready to accept requests. This endpoint is only available in the dev server and does not exist in production builds. diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 803270fad5c5c..41c3bcb1662b9 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -280,6 +280,48 @@ The following hotkeys can be used in the terminal where the Astro preview server The `astro preview` command can be combined with the [common flags](#common-flags) documented below to further control the preview experience. +

Flags

+ +

+ +#### `--background` + +Starts the preview server as a detached background process and enables [JSON logging](#--json). This flag is provided automatically when an AI agent is detected. You can also use it manually: + +```shell +astro preview --background +``` + +If a server is already running for the project, the command prints the existing server's info and exits without starting a new one. Use the `--force` flag to stop the existing server and start a new one. + +```shell +astro preview --background --force +``` + +See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection. + +

Subcommands

+ +

+ +#### `astro preview stop` + +Stops a running background preview server. Sends `SIGTERM` and waits up to 5 seconds for the server to exit gracefully. If the process is still running after that, it escalates to `SIGKILL`. + +#### `astro preview status` + +Checks whether a background preview server is running and displays its URL, PID, and uptime. + +#### `astro preview logs` + +Displays logs from a background preview server. Only works when the server was started with `astro preview --background`, since foreground servers write logs directly to the terminal. + +##### Flags + +###### `--follow` (`-f`) + +Streams new log output as it's written, similar to `tail -f`. Without this flag, the current log file contents are printed and the command exits. + ## `astro check` Runs diagnostics (such as type-checking within `.astro` files) against your project and reports errors to the console. If any errors are found the process will exit with a code of **1**. From 9010a427219159a76b087ae20136f24181830c4d Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 4 Aug 2026 15:36:36 -0400 Subject: [PATCH 2/5] Consolidate dev/preview background docs into common sections --- src/content/docs/en/guides/build-with-ai.mdx | 23 +--- .../docs/en/reference/cli-reference.mdx | 126 ++++++------------ 2 files changed, 49 insertions(+), 100 deletions(-) diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx index 5df83e0157080..caa15ed7bdd35 100644 --- a/src/content/docs/en/guides/build-with-ai.mdx +++ b/src/content/docs/en/guides/build-with-ai.mdx @@ -362,33 +362,20 @@ The same technology that powers Astro's MCP server is also available as a chatbo

-When an AI coding agent is detected, `astro dev` automatically starts the dev server as a detached background process. This prevents the dev server from blocking the agent's terminal and allows it to continue working while the server runs. +When an AI coding agent is detected, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs. -A lock file (`.astro/dev.json`) is written when the dev server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project. +A lock file (`.astro/dev.json` or `.astro/preview.json`) is written when the server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project. -If you are not using an AI coding agent, `astro dev` starts in the foreground process and logs to the terminal. +If you are not using an AI coding agent, the server starts in the foreground process and logs to the terminal. -To opt out of automatic background mode, set the `ASTRO_DEV_BACKGROUND` environment variable before running `astro dev`: +To opt out of automatic background mode, set the `ASTRO_DEV_BACKGROUND` or `ASTRO_PREVIEW_BACKGROUND` environment variable before running the command: ```shell ASTRO_DEV_BACKGROUND=0 astro dev -``` - -See the [CLI reference](/en/reference/cli-reference/#astro-dev) for the full list of `astro dev` flags and subcommands. - -### Preview servers - -

- -The `astro preview` command uses the same background mode as `astro dev`. When an AI coding agent is detected, or when you pass the [`--background` flag](/en/reference/cli-reference/#--background-1), the preview server starts as a detached background process and writes a lock file (`.astro/preview.json`) recording its URL, port, and PID. - -To opt out of automatic background mode, set the `ASTRO_PREVIEW_BACKGROUND` environment variable before running `astro preview`: - -```shell ASTRO_PREVIEW_BACKGROUND=0 astro preview ``` -See the [CLI reference](/en/reference/cli-reference/#astro-preview) for the full list of `astro preview` flags and subcommands. +See the CLI reference for the full list of flags and subcommands for [`astro dev`](/en/reference/cli-reference/#astro-dev) and [`astro preview`](/en/reference/cli-reference/#astro-preview). ### Health endpoint diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 41c3bcb1662b9..5d66c490ff62a 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -202,22 +202,6 @@ The following hotkeys can be used in the terminal where the Astro development se The command accepts [common flags](#common-flags) and the following additional flags. -#### `--background` - -Starts the dev server as a detached background process and enables [JSON logging](#--json). This flag is provided automatically when an AI agent is detected. You can also use it manually: - -```shell -astro dev --background -``` - -If a server is already running for the project, the command prints the existing server's info and exits without starting a new one. Use the `--force` flag to stop the existing server and start a new one. - -```shell -astro dev --background --force -``` - -See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint. - #### `--ignore-lock`

@@ -228,32 +212,10 @@ Starts the dev server without checking or writing the lock file used to detect o astro dev --ignore-lock --port 4322 ``` -The new server is not tracked by `astro dev stop`, `astro dev status`, or `astro dev logs`. +The new server is not tracked by the [`stop`, `status`, or `logs` subcommands](#common-subcommands). When combined with `--background` (including when triggered by an AI coding agent) or `--force`, an error is thrown, as both rely on the lock file. -

Subcommands

- -

- -#### `astro dev stop` - -Stops a running background dev server. Sends `SIGTERM` and waits up to 5 seconds for the server to exit gracefully. If the process is still running after that, it escalates to `SIGKILL`. - -#### `astro dev status` - -Checks whether a background dev server is running and displays its URL, PID, and uptime. - -#### `astro dev logs` - -Displays logs from a background dev server. Only works when the server was started with `astro dev --background`, since foreground servers write logs directly to the terminal. - -##### Flags - -###### `--follow` (`-f`) - -Streams new log output as it's written, similar to `tail -f`. Without this flag, the current log file contents are printed and the command exits. - ## `astro build` Builds your site for deployment. By default, this will generate static files and place them in a `dist/` directory. If any routes are [rendered on demand](/en/guides/on-demand-rendering/), this will generate the necessary server files to serve your site. @@ -278,49 +240,7 @@ The following hotkeys can be used in the terminal where the Astro preview server - `o` + `enter` to open your Astro site in the browser. - `q` + `enter` to quit the preview server. -The `astro preview` command can be combined with the [common flags](#common-flags) documented below to further control the preview experience. - -

Flags

- -

- -#### `--background` - -Starts the preview server as a detached background process and enables [JSON logging](#--json). This flag is provided automatically when an AI agent is detected. You can also use it manually: - -```shell -astro preview --background -``` - -If a server is already running for the project, the command prints the existing server's info and exits without starting a new one. Use the `--force` flag to stop the existing server and start a new one. - -```shell -astro preview --background --force -``` - -See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection. - -

Subcommands

- -

- -#### `astro preview stop` - -Stops a running background preview server. Sends `SIGTERM` and waits up to 5 seconds for the server to exit gracefully. If the process is still running after that, it escalates to `SIGKILL`. - -#### `astro preview status` - -Checks whether a background preview server is running and displays its URL, PID, and uptime. - -#### `astro preview logs` - -Displays logs from a background preview server. Only works when the server was started with `astro preview --background`, since foreground servers write logs directly to the terminal. - -##### Flags - -###### `--follow` (`-f`) - -Streams new log output as it's written, similar to `tail -f`. Without this flag, the current log file contents are printed and the command exits. +The `astro preview` command can be combined with the [common flags](#common-flags) documented below to further control the preview experience. Since v7.2.0, it also accepts the [`--background` flag](#--background) and the [`stop`, `status`, and `logs` subcommands](#common-subcommands) to manage a background preview server. ## `astro check` @@ -505,6 +425,30 @@ astro create-key Set this key as the `ASTRO_KEY` environment variable (e.g. in a `.env` file) and include it in your CI/CD or host’s build settings when you need [a constant encryption key for your server islands](/en/guides/server-islands/#reusing-the-encryption-key) for situations like rolling deployments, multi-region hosting or a CDN that caches pages containing server islands. +## Common subcommands + +

+ +The commands [`astro dev`](#astro-dev) and, since version v7.2.0, [`astro preview`](#astro-preview) accept the following subcommands to manage a [background server](#--background). + +### `stop` + +Stops a running background server. Sends `SIGTERM` and waits up to 5 seconds for the server to exit gracefully. If the process is still running after that, it escalates to `SIGKILL`. + +### `status` + +Checks whether a background server is running and displays its URL, PID, and uptime. + +### `logs` + +Displays logs from a background server. Only works when the server was started with the [`--background` flag](#--background), since foreground servers write logs directly to the terminal. + +#### Flags + +##### `--follow` (`-f`) + +Streams new log output as it's written, similar to `tail -f`. Without this flag, the current log file contents are printed and the command exits. + ## Common flags ### `--root ` @@ -588,6 +532,24 @@ Enables silent logging, which will run the server without any console output. Automatically opens the app in the browser on server start. Can be passed a full URL string (e.g. `--open http://example.com`) or a pathname (e.g. `--open /about`) to specify the URL to open. +### `--background` + +

+ +Starts the dev server, or the preview server since v7.2.0, as a detached background process and enables [JSON logging](#--json). This flag is provided automatically when an AI agent is detected. You can also use it manually: + +```shell +astro dev --background +``` + +If a server is already running for the project, the command prints the existing server's info and exits without starting a new one. Use the `--force` flag to stop the existing server and start a new one. + +```shell +astro dev --background --force +``` + +See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint. + ### `--json`

From 801d48aa0ffa58f1fc8bed98182763d1b4256453 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 4 Aug 2026 16:31:02 -0400 Subject: [PATCH 3/5] Document PreviewServer.urls for adapter authors --- src/content/docs/en/reference/adapter-reference.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index ecfffc301923a..379f225456bfe 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -1039,7 +1039,7 @@ Describes the function an adapter should export to start a preview server when [

-**Type:** `{ host?: string; port: number; closed(): Promise; stop(): Promise; }` +**Type:** `{ host?: string; port: number; urls?: { local: string[]; network: string[] }; closed(): Promise; stop(): Promise; }`

Describes an instance of a preview server for the adapter. @@ -1062,6 +1062,16 @@ Defines the host the preview server is listening on. Defines the port the preview server is listening on. +#### `PreviewServer.urls` + +

+ +**Type:** `{ local: string[]; network: string[] } | undefined`
+ +

+ +Defines the resolved URLs the preview server is listening on, grouped into `local` (loopback addresses) and `network` (LAN and public addresses). Astro uses these to record the server's address in the lock file when the preview server runs in the background. + #### `PreviewServer.closed()`

From 910efdffcd3d8b06388625cb13bb1fb40c4163b3 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 4 Aug 2026 17:42:36 -0400 Subject: [PATCH 4/5] Update src/content/docs/en/reference/cli-reference.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/reference/cli-reference.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 5d66c490ff62a..98442f1ecac00 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -536,7 +536,11 @@ Automatically opens the app in the browser on server start. Can be passed a full

-Starts the dev server, or the preview server since v7.2.0, as a detached background process and enables [JSON logging](#--json). This flag is provided automatically when an AI agent is detected. You can also use it manually: +Starts the dev server, or the preview server since v7.2.0, as a detached background process and enables [JSON logging](#--json). + +When the server starts, Astro writes a lock file (`.astro/dev.json` or `.astro/preview.json`) to record the server's URL, port, and PID. This avoids launching many instances of the server for the same project. + +This flag is provided automatically when an AI agent is detected. You can also use it manually: ```shell astro dev --background From 17df50c7b579b26d1a2eb339be2806cb7e5f4bf0 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 4 Aug 2026 17:42:46 -0400 Subject: [PATCH 5/5] Update src/content/docs/en/reference/adapter-reference.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 379f225456bfe..cada6e11c5032 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -1070,7 +1070,7 @@ Defines the port the preview server is listening on.

-Defines the resolved URLs the preview server is listening on, grouped into `local` (loopback addresses) and `network` (LAN and public addresses). Astro uses these to record the server's address in the lock file when the preview server runs in the background. +Defines the resolved URLs the preview server is listening on, grouped into `local` (loopback addresses) and `network` (LAN and public addresses). Astro uses these to record the server's address in the lock file [when the preview server runs in the background](/en/reference/cli-reference/#--background). #### `PreviewServer.closed()`