diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx index 5763d582929f9..caa15ed7bdd35 100644 --- a/src/content/docs/en/guides/build-with-ai.mdx +++ b/src/content/docs/en/guides/build-with-ai.mdx @@ -362,19 +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 +ASTRO_PREVIEW_BACKGROUND=0 astro preview ``` -See the [CLI reference](/en/reference/cli-reference/#astro-dev) for the full list of `astro dev` 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/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index ecfffc301923a..cada6e11c5032 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](/en/reference/cli-reference/#--background). + #### `PreviewServer.closed()`

diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 803270fad5c5c..98442f1ecac00 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,7 +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. +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` @@ -463,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 ` @@ -546,6 +532,28 @@ 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). + +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 +``` + +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`