diff --git a/astro.sidebar.ts b/astro.sidebar.ts index 620f9ce7edf80..82405ff4c5ffc 100644 --- a/astro.sidebar.ts +++ b/astro.sidebar.ts @@ -164,6 +164,7 @@ export const sidebar = [ 'reference/experimental-flags/chrome-devtools-workspace', 'reference/experimental-flags/svg-optimization', 'reference/experimental-flags/collection-storage', + 'reference/experimental-flags/incremental-build', ], }), 'reference/legacy-flags', 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/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index c9f5b39c2c6f7..af8c90f79a88d 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -116,7 +116,7 @@ It also accepts the following: ### `imageService`

-**Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' }`
+**Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile' | 'cloudflare-binding', runtime?: 'cloudflare-binding' | 'passthrough' }`
**Default:** `'cloudflare-binding'`

@@ -128,7 +128,11 @@ Determines which image service is used by the adapter. The adapter will default - **`compile`:** Uses the [configured image service](/en/reference/configuration-reference/#imageservice) or falls back to a combination of internal dependencies to transform images locally at build time for prerendered routes. The noop `passthrough` option is configured for on-demand rendered pages. - **`custom`:** Uses the [configured image service](/en/reference/configuration-reference/#imageservice) (defaults to Sharp) to process assets at build time for prerendered routes. Bundles the image service for runtime image handling, without checking its compatibility with Cloudflare's `workerd` runtime. -It is also possible to configure your image service as an object, setting both a build time and runtime service independently. Currently, `'compile'` is the only available build-time option. The supported runtime options are `'passthrough'` (default) and `'cloudflare-binding'`: +

+ +You can also configure the image service as an object by providing a build-time service (`compile` or `cloudflare-binding`) and, optionally, a runtime service (`passthrough` or `cloudflare-binding`). + +When the runtime service is omitted, its default value depends on the configured build-time service. It falls back to `'passthrough'` for `build: 'compile'` and to `'cloudflare-binding'` for `build: 'cloudflare-binding'`. ```js title="astro.config.mjs" ins={6} import { defineConfig } from 'astro/config'; @@ -141,6 +145,21 @@ export default defineConfig({ }); ``` +Using `imageService: 'cloudflare-binding'` enables image optimization using the [Cloudflare Images binding](https://developers.cloudflare.com/images/transform-images/bindings/) only at runtime. + +To opt in to build-time image optimization with the binding during `workerd` prerendering, set `build` to `'cloudflare-binding'`. If the binding fails to transform an image at build time, the adapter falls back to the [configured image service](/en/reference/configuration-reference/#imageservice) (defaults to Sharp). + +```js title="astro.config.mjs" ins={6} +import { defineConfig } from 'astro/config'; +import cloudflare from '@astrojs/cloudflare'; + +export default defineConfig({ + adapter: cloudflare({ + imageService: { build: 'cloudflare-binding', runtime: 'cloudflare-binding' } + }), +}); +``` + ### `sessionKVBindingName`

@@ -354,6 +373,8 @@ const cart = await Astro.session?.get('cart'); By default, the KV binding is named `SESSION`. To use a different name, set the [`sessionKVBindingName`](#sessionkvbindingname) option in the adapter config. +If your project does not use sessions, you can set [`session: false`](/en/guides/sessions/#disabling-sessions) in your Astro config. The adapter will not configure a KV binding, no KV namespace will be provisioned when you deploy, and the session runtime will be excluded from your Worker bundle. + :::note Writes to Cloudflare KV are [eventually consistent](https://developers.cloudflare.com/kv/concepts/how-kv-works/#consistency) between regions. This means that changes are available immediately within the same region but may take up to 60 seconds to propagate globally. This won't affect most users as they are unlikely to switch regions between requests, but it may be a consideration for some use cases, such as VPN users. ::: diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index 9af376c29f86f..f7074c8bec7d8 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -216,6 +216,8 @@ The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user d Astro automatically configures [Netlify Blobs](https://docs.netlify.com/blobs/overview/) for session storage when using the Netlify adapter. If you would prefer to use a different session storage driver, you can specify it in your Astro config. See [the `session` configuration reference](/en/reference/configuration-reference/#sessiondriver) for more details. +If your project does not use sessions, you can set [`session: false`](/en/guides/sessions/#disabling-sessions) in your Astro config. The adapter will not configure Netlify Blobs for session storage, and the session runtime will be excluded from your function bundle. + ### Caching Pages On-demand rendered pages without any dynamic content can be cached to improve performance and lower resource usage. diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index aab128b0774d8..7acd298fe0b16 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -295,6 +295,8 @@ The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user d Astro uses the local filesystem for session storage when using the Node adapter. If you would prefer to use a different session storage driver, you can specify it in your Astro config. See [the `session` configuration reference](/en/reference/configuration-reference/#sessiondriver) for more details. +If your project does not use sessions, you can set [`session: false`](/en/guides/sessions/#disabling-sessions) in your Astro config. The adapter will not configure the filesystem session driver, and the session runtime will be excluded from your server bundle. + ## Environment variables When using the [`astro:env`](/en/guides/environment-variables/#type-safe-environment-variables) secrets or `process.env` at runtime, neither Astro nor the adapter loads environment variables for you. diff --git a/src/content/docs/en/guides/sessions.mdx b/src/content/docs/en/guides/sessions.mdx index b10a0a7581941..d8c665dac9e36 100644 --- a/src/content/docs/en/guides/sessions.mdx +++ b/src/content/docs/en/guides/sessions.mdx @@ -110,6 +110,24 @@ The following example takes advantage of [Unstorage compatibility](/en/reference ``` +### Disabling sessions + +

+ +

+ +The session runtime is automatically excluded from your server bundle whenever no session driver is configured. Setting `session: false` additionally tells your adapter not to provide its default driver, opting your project out of session support entirely: + +```js title="astro.config.mjs" ins={4} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + session: false, +}); +``` + +Adapters that normally provide a default session driver (e.g. [Node](/en/guides/integrations-guide/node/#sessions), [Cloudflare](/en/guides/integrations-guide/cloudflare/#sessions), and [Netlify](/en/guides/integrations-guide/netlify/#sessions)) will not configure one. This can be useful for serverless and edge runtimes, where a smaller bundle reduces cold start time. + ## Interacting with session data The [`session` object](/en/reference/api-reference/#session) allows you to interact with the stored user state (e.g. adding items to a shopping cart) and the session ID (e.g. deleting the session ID cookie when logging out). The object is accessible as `Astro.session` in your Astro components and pages and as `context.session` object in API endpoints, middleware, and actions. 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/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index f625b698cff42..d164608b32f0d 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -893,7 +893,7 @@ Allows customizing how the cookie is serialized.

-**Type:** `AstroSession` +**Type:** `AstroSession | undefined` @@ -901,7 +901,7 @@ Allows customizing how the cookie is serialized. `session` is an object that allows data to be stored between requests for [routes rendered on demand](/en/guides/on-demand-rendering/). It is associated with a cookie that contains the session ID only: the data itself is not stored in the cookie. -The session is created when first used, and the session cookie is automatically set. The `session` object is `undefined` if no session storage has been configured, or if the current route is prerendered, and will log an error if you try to use it. +The session is created when first used, and the session cookie is automatically set. The `session` object is `undefined` and will log an error when used in the following cases: no session storage has been configured, [sessions are disabled](/en/guides/sessions/#disabling-sessions), or the current route is prerendered. See [the session guide](/en/guides/sessions/) for more information on how to use sessions in your Astro project. 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`

diff --git a/src/content/docs/en/reference/configuration-reference.mdx b/src/content/docs/en/reference/configuration-reference.mdx index 660d66badc9c6..a24147d8039d6 100644 --- a/src/content/docs/en/reference/configuration-reference.mdx +++ b/src/content/docs/en/reference/configuration-reference.mdx @@ -1437,7 +1437,8 @@ See [the logger API reference](/en/reference/logger-reference/) for more informa

The entrypoint for the [logger implementation](/en/reference/logger-reference/#the-logger-implementation). -This can be an npm package, or a `URL` pointing to a file in your project: +This can be an npm package, a path relative to your project root, or a `URL` pointing to a +file in your project: ```js title="astro.config.mjs" import { defineConfig } from 'astro/config'; @@ -1480,6 +1481,7 @@ export default defineConfig({

+**Type:** `object | false`

@@ -1502,6 +1504,16 @@ export default defineConfig({ Session drivers are configured at build time. This means environment variables used in the driver configuration are inlined. You must create your own driver entrypoint to [override the configuration at runtime](/en/guides/sessions/#overriding-the-configuration-at-runtime). +Since Astro v7.2.0, you can opt out of session support by setting the option to `false`. When sessions are disabled, the session runtime is excluded from the SSR bundle, and adapters skip wiring their default session driver. This is useful for serverless and edge runtimes where bundle parse time is sensitive. + +```js title="astro.config.mjs" +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + session: false, +}); +``` + See [the sessions guide](/en/guides/sessions/) for more information. ### session.driver diff --git a/src/content/docs/en/reference/experimental-flags/incremental-build.mdx b/src/content/docs/en/reference/experimental-flags/incremental-build.mdx new file mode 100644 index 0000000000000..cd38e2a5f226b --- /dev/null +++ b/src/content/docs/en/reference/experimental-flags/incremental-build.mdx @@ -0,0 +1,98 @@ +--- +title: Experimental incremental static builds +sidebar: + label: Incremental builds +i18nReady: true +--- + +import Since from '~/components/Since.astro' + +

+ +**Type:** `boolean`
+**Default:** `false`
+ +

+ +This experimental feature reuses the output of a previous build so that unchanged pages are not rendered again. + +When enabled, Astro can skip a static page generated by [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths) if both its data and the code it depends on are unchanged since the last build. You mark a page's data by returning a `cacheKey` for it, and Astro tracks the code by hashing the page's module dependency graph. When both match the previous build, Astro copies the earlier output instead of rendering the page again. + +On large sites where most pages change infrequently, this can reduce build times significantly because rendering is skipped for pages that would produce identical output. + +To enable incremental builds, add the flag to your Astro config: + +```js title="astro.config.mjs" ins={5} +import { defineConfig } from "astro/config"; + +export default defineConfig({ + experimental: { + incrementalBuild: true, + }, +}); +``` + +## Providing a cache key + +Only pages returned from `getStaticPaths()` that include a `cacheKey` can be skipped. Every other page, including static pages that do not use `getStaticPaths()`, is rendered on each build. + +A `cacheKey` is a string that identifies the data used to render a page. Choose a value that changes whenever the page's content changes, such as a content hash, a version number, or an updated timestamp from your data source. Astro re-renders the page when its `cacheKey` differs from the previous build, and reuses the previous output when it is the same. + +```astro title="src/pages/blog/[slug].astro" +--- +export async function getStaticPaths() { + const posts = await fetchPosts(); + + return posts.map((post) => ({ + params: { slug: post.slug }, + props: { post }, + cacheKey: post.updatedAt, + })); +} +--- +``` + +When you generate pages from a [content collection](/en/guides/content-collections/), a loader can provide a [`digest`](/en/reference/content-loader-reference/#dataentrydigest) for each entry. The loader is responsible for updating this value whenever the entry's data changes. This makes it a convenient `cacheKey`: + +```astro title="src/pages/docs/[...slug].astro" +--- +import { getCollection, render } from "astro:content"; + +export async function getStaticPaths() { + const entries = await getCollection("docs"); + + return entries.map((entry) => ({ + params: { slug: entry.id }, + props: { entry }, + cacheKey: String(entry.digest), + })); +} + +const { entry } = Astro.props; +const { Content } = await render(entry); +--- +``` + +## How pages are invalidated + +A page with a matching `cacheKey` is still re-rendered when the code it relies on changes. Astro hashes the page's module dependency graph, including the contents of its layouts, components, and imported files, so editing any of them invalidates the pages that use them. Changing your Astro configuration or your project's dependencies invalidates the entire cache, since those can affect the output of every page. + +Pages that are removed from `getStaticPaths()` between builds have their previous output cleaned up automatically. + +## Preserving the cache between builds + +Astro stores the incremental cache in your project's [`cacheDir`](/en/reference/configuration-reference/#cachedir), which is `node_modules/.astro/` by default. This holds both the build manifest and the reusable output of previously-rendered pages. The output directory is emptied at the start of every build, and skipped pages are restored from `cacheDir`. + +For pages to be skipped in a continuous integration environment, `cacheDir` must be restored before running `astro build`. Cache and restore this single directory between builds; nothing else needs to persist. If it is missing, Astro re-renders every page. + +To ignore the cache and re-render every page, run `astro build --force`. Astro still writes a fresh cache for the next build. + +## Limitations + +This experimental feature currently has the following limitations: + +- **`build.concurrency`**: The incremental cache is disabled when [`build.concurrency`](/en/reference/configuration-reference/#buildconcurrency) is greater than `1`. Astro logs a warning and re-renders every page. + +- **Server islands**: Pages that renders [server islands](/en/guides/server-islands/) embed props with a key that is [regenerated on each build by default](/en/guides/server-islands/#reusing-the-encryption-key). They are re-rendered every time. To cache these pages and reuse them between builds, set a stable `ASTRO_KEY`. Changing the key invalidates them, ensuring that their embedded content stays decryptable. + +- **Middleware**: Changes to your [middleware](/en/guides/middleware/) do not invalidate cached pages. If your middleware changes the HTML of prerendered pages, run `astro build --force` after editing it. diff --git a/src/content/docs/en/reference/modules/astro-fetch.mdx b/src/content/docs/en/reference/modules/astro-fetch.mdx index dfc6c6250447b..bdb74f9ca3907 100644 --- a/src/content/docs/en/reference/modules/astro-fetch.mdx +++ b/src/content/docs/en/reference/modules/astro-fetch.mdx @@ -306,6 +306,8 @@ export default { }; ``` +This handler registers no provider when no session driver is configured, or when [sessions are disabled](/en/guides/sessions/#disabling-sessions). In both cases, `ctx.session` will be `undefined`. + ### `trailingSlash()`