Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions src/content/docs/en/guides/build-with-ai.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -362,19 +362,20 @@ The same technology that powers Astro's MCP server is also available as a chatbo

<p><Since v="7.0.0" /></p>

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
```

<ReadMore>See the [CLI reference](/en/reference/cli-reference/#astro-dev) for the full list of `astro dev` flags and subcommands.</ReadMore>
<ReadMore>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).</ReadMore>

### Health endpoint

Expand Down
12 changes: 11 additions & 1 deletion src/content/docs/en/reference/adapter-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1039,7 +1039,7 @@ Describes the function an adapter should export to start a preview server when [

<p>

**Type:** `{ host?: string; port: number; closed(): Promise<void>; stop(): Promise<void>; }`
**Type:** `{ host?: string; port: number; urls?: { local: string[]; network: string[] }; closed(): Promise<void>; stop(): Promise<void>; }`
</p>

Describes an instance of a preview server for the adapter.
Expand All @@ -1062,6 +1062,16 @@ Defines the host the preview server is listening on.

Defines the port the preview server is listening on.

#### `PreviewServer.urls`

<p>

**Type:** `{ local: string[]; network: string[] } | undefined`<br />
<Since v="7.2.0" />
</p>

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()`

<p>
Expand Down
88 changes: 48 additions & 40 deletions src/content/docs/en/reference/cli-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

<ReadMore>See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint.</ReadMore>

#### `--ignore-lock`

<p><Since v="7.1.0" /></p>
Expand All @@ -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.

<h3>Subcommands</h3>

<p><Since v="7.0.0" /></p>

#### `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.
Expand All @@ -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`

Expand Down Expand Up @@ -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

<p><Since v="7.0.0" /></p>

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 <path>`
Expand Down Expand Up @@ -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`

<p><Since v="7.0.0" /></p>

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
```

<ReadMore>See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint.</ReadMore>

### `--json`

<p><Since v="7.0.0" /></p>
Expand Down
Loading