From 88af41740a4f76b019e76432f9d5ec139d872ed2 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 28 Nov 2025 12:31:57 -0500 Subject: [PATCH 01/22] docs: document Environment API breaking changes --- src/content/docs/en/guides/upgrade-to/v6.mdx | 144 +++++++++++++++++++ 1 file changed, 144 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 59b159dff19e9..0d9cb7799df4f 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -97,6 +97,150 @@ Astro v6.0 upgrades to Vite v7.0 as the development server and production bundle If you are using Vite-specific plugins, configuration, or APIs, check the [Vite migration guide](https://vite.dev/guide/migration) for their breaking changes and upgrade your project as needed. +## Environment API Changes + +Astro v6.0 introduces significant changes to how Astro manages different runtime environments (client, server, and prerender) using Vite's new Environments API. Integration and adapter maintainers should pay special attention to these changes. + +### Vite Environments API Integration + + + +Build configuration and dev server interactions now use Vite's new Environments API. Integration hooks and HMR access patterns have changed. + +#### What should I do? + +**For integrations using `astro:build:setup`:** + +The hook is now called once with all environments, instead of being called separately for each build target. Remove the `target` parameter and use `vite.environments` to configure specific environments: + +```ts title="my-integration.mjs" del={3-6} ins={3-5} +{ + hooks: { + 'astro:build:setup': ({ target, vite }) => { + if (target === 'client') { + vite.build.minify = false; + } + } + } +} +``` + +```ts title="my-integration.mjs" +{ + hooks: { + 'astro:build:setup': ({ vite }) => { + vite.environments.client.build.minify = false; + } + } +} +``` + +**For dev toolbar and integration code accessing HMR:** + +Replace `server.hot.send()` with `server.environments.client.hot.send()`: + +```ts del={1} ins={2} +server.hot.send(event) +server.environments.client.hot.send(event) +``` + +Learn more about [Vite Environments API](https://vite.dev/guide/api-environment) and [integration hooks](/en/reference/integrations-reference/#astrobuildsetup). + +### SSRManifest Structure Changes + + + +The `SSRManifest` interface has structural changes. If you're reading values from the manifest in integrations, note these changes: + +#### What should I do? + +**Path properties are now `URL` objects:** + +When accessing path properties like `srcDir`, `outDir`, `cacheDir`, `publicDir`, `buildClientDir`, and `buildServerDir`, they are now `URL` objects instead of URL strings. If you were treating them as strings, you'll need to handle the `URL` object: + +```ts del={1} ins={2} +const srcPath = manifest.srcDir; // was a URL string like "file:///path/to/src" +const srcPath = manifest.srcDir; // now a URL object +``` + +**New properties available:** + +The manifest now includes: +- `rootDir: URL` — Root directory of the project +- `assetsDir: string` — Directory containing built assets +- `serverLike: boolean` — Whether this is a server-like environment +- `logLevel: LoggerLevel` — Logging level + +**Removed `hrefRoot` property:** + +The `hrefRoot` property is no longer available on the manifest. + +**Async methods for dynamic data:** + +When accessing `serverIslandMappings` and `sessionDriver`, they are now async methods: + +```ts del={1,2} ins={3,4} +const mappings = manifest.serverIslandMappings; +const driver = manifest.sessionDriver; +const mappings = await manifest.serverIslandMappings?.(); +const driver = await manifest.sessionDriver?.(); +``` + +Learn more about [the Adapter API](/en/reference/adapter-reference/). + +### RouteData.generate() Removed + + + +The `generate()` method on `RouteData` has been removed. Route generation is now handled internally by Astro. + +#### What should I do? + +Remove any calls to `route.generate()` in your code. This method is no longer needed: + +```ts del={1} +const generated = route.generate(params); +``` + +Learn more about [routing](/en/guides/routing/). + +### Percent-Encoding Security Fix + + + +Routes with `%25` (percent-encoded percent sign) in filenames are no longer supported in static builds for security reasons. + +#### What should I do? + +If you have route files with `%25` in the filename, rename them to use a different character: + +```bash del={1} ins={2} +src/pages/test%25file.astro +src/pages/test-file.astro +``` + +This restriction prevents encoding-based security bypasses where `%25` decodes to `%`, potentially leading to ambiguous or invalid encoding sequences. + +### astro:ssr-manifest Virtual Module Removed + + + +The `astro:ssr-manifest` virtual module has been removed entirely. It is no longer used by integrations or internally by Astro. + +#### What should I do? + +If your integration or code imports from `astro:ssr-manifest`, use `astro:config/server` instead to access configuration values: + +```ts del={1} ins={2,3} +import { manifest } from 'astro:ssr-manifest'; +import { srcDir, outDir, root } from 'astro:config/server'; +// Use srcDir, outDir, root, etc. for configuration values +``` + +The manifest is now passed directly through integration hooks and adapter APIs rather than through a virtual module. For build-specific manifest data, use the `astro:build:ssr` integration hook which receives the manifest as a parameter. + +Learn more about [the `astro:config` virtual module](/en/reference/modules/astro-config/). + ## Legacy The following features are now considered legacy features. They should function normally but are no longer recommended and are in maintenance mode. They will see no future improvements and documentation will not be updated. These features will eventually be deprecated, and then removed entirely. From f77b4902aadb857bee3ee03fc9bdc63ef71f7cbe Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Sat, 29 Nov 2025 12:09:46 -0500 Subject: [PATCH 02/22] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 0d9cb7799df4f..c867ea12cc6c5 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -161,6 +161,10 @@ When accessing path properties like `srcDir`, `outDir`, `cacheDir`, `publicDir`, ```ts del={1} ins={2} const srcPath = manifest.srcDir; // was a URL string like "file:///path/to/src" const srcPath = manifest.srcDir; // now a URL object +```ts del={2} ins={3} +// To retrieve the same format (e.g., "file:///path/to/src"), make the following change: +const srcPath = manifest.srcDir; +const srcPath = manifest.srcDir.href; ``` **New properties available:** From 52f9cf86bcf9977818cc24bd5ef9d96c708c4266 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Sat, 29 Nov 2025 12:10:04 -0500 Subject: [PATCH 03/22] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index c867ea12cc6c5..36c66635d26f6 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -208,7 +208,7 @@ const generated = route.generate(params); Learn more about [routing](/en/guides/routing/). -### Percent-Encoding Security Fix +### Changed: Percent-Encoding Security Fix From 0ca67aab5eca557693fd74c1248b8fe3db9e3e07 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Sat, 29 Nov 2025 12:10:10 -0500 Subject: [PATCH 04/22] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 36c66635d26f6..3697e9fbb8c3d 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -225,7 +225,7 @@ src/pages/test-file.astro This restriction prevents encoding-based security bypasses where `%25` decodes to `%`, potentially leading to ambiguous or invalid encoding sequences. -### astro:ssr-manifest Virtual Module Removed +### Removed: `astro:ssr-manifest` virtual module From 0457ca46bcca7ab83d02c42ccedfdfba98c44c70 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Sat, 29 Nov 2025 12:10:26 -0500 Subject: [PATCH 05/22] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 3697e9fbb8c3d..d36beae7dfdb6 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -113,7 +113,7 @@ Build configuration and dev server interactions now use Vite's new Environments The hook is now called once with all environments, instead of being called separately for each build target. Remove the `target` parameter and use `vite.environments` to configure specific environments: -```ts title="my-integration.mjs" del={3-6} ins={3-5} +```ts title="my-integration.mjs" del={3-7} ins={8-10} { hooks: { 'astro:build:setup': ({ target, vite }) => { @@ -121,13 +121,6 @@ The hook is now called once with all environments, instead of being called separ vite.build.minify = false; } } - } -} -``` - -```ts title="my-integration.mjs" -{ - hooks: { 'astro:build:setup': ({ vite }) => { vite.environments.client.build.minify = false; } From 6b4673968ae539f1525a06b0c3f7ea37d6375570 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Sat, 29 Nov 2025 12:12:22 -0500 Subject: [PATCH 06/22] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index d36beae7dfdb6..850a909fdeecc 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -185,7 +185,7 @@ const driver = await manifest.sessionDriver?.(); Learn more about [the Adapter API](/en/reference/adapter-reference/). -### RouteData.generate() Removed +### Removed: `RouteData.generate()` From 6fb050d0cb7d67b0ed4cde3cd8c6112fb7509b05 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Mon, 1 Dec 2025 15:28:31 -0400 Subject: [PATCH 07/22] reorganize content --- src/content/docs/en/guides/upgrade-to/v6.mdx | 292 ++++++++++--------- 1 file changed, 157 insertions(+), 135 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 850a909fdeecc..e820be143250e 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -97,146 +97,19 @@ Astro v6.0 upgrades to Vite v7.0 as the development server and production bundle If you are using Vite-specific plugins, configuration, or APIs, check the [Vite migration guide](https://vite.dev/guide/migration) for their breaking changes and upgrade your project as needed. -## Environment API Changes - -Astro v6.0 introduces significant changes to how Astro manages different runtime environments (client, server, and prerender) using Vite's new Environments API. Integration and adapter maintainers should pay special attention to these changes. - -### Vite Environments API Integration - - - -Build configuration and dev server interactions now use Vite's new Environments API. Integration hooks and HMR access patterns have changed. - -#### What should I do? - -**For integrations using `astro:build:setup`:** - -The hook is now called once with all environments, instead of being called separately for each build target. Remove the `target` parameter and use `vite.environments` to configure specific environments: - -```ts title="my-integration.mjs" del={3-7} ins={8-10} -{ - hooks: { - 'astro:build:setup': ({ target, vite }) => { - if (target === 'client') { - vite.build.minify = false; - } - } - 'astro:build:setup': ({ vite }) => { - vite.environments.client.build.minify = false; - } - } -} -``` - -**For dev toolbar and integration code accessing HMR:** - -Replace `server.hot.send()` with `server.environments.client.hot.send()`: - -```ts del={1} ins={2} -server.hot.send(event) -server.environments.client.hot.send(event) -``` - -Learn more about [Vite Environments API](https://vite.dev/guide/api-environment) and [integration hooks](/en/reference/integrations-reference/#astrobuildsetup). - -### SSRManifest Structure Changes - - - -The `SSRManifest` interface has structural changes. If you're reading values from the manifest in integrations, note these changes: - -#### What should I do? - -**Path properties are now `URL` objects:** - -When accessing path properties like `srcDir`, `outDir`, `cacheDir`, `publicDir`, `buildClientDir`, and `buildServerDir`, they are now `URL` objects instead of URL strings. If you were treating them as strings, you'll need to handle the `URL` object: - -```ts del={1} ins={2} -const srcPath = manifest.srcDir; // was a URL string like "file:///path/to/src" -const srcPath = manifest.srcDir; // now a URL object -```ts del={2} ins={3} -// To retrieve the same format (e.g., "file:///path/to/src"), make the following change: -const srcPath = manifest.srcDir; -const srcPath = manifest.srcDir.href; -``` - -**New properties available:** - -The manifest now includes: -- `rootDir: URL` — Root directory of the project -- `assetsDir: string` — Directory containing built assets -- `serverLike: boolean` — Whether this is a server-like environment -- `logLevel: LoggerLevel` — Logging level - -**Removed `hrefRoot` property:** - -The `hrefRoot` property is no longer available on the manifest. - -**Async methods for dynamic data:** - -When accessing `serverIslandMappings` and `sessionDriver`, they are now async methods: - -```ts del={1,2} ins={3,4} -const mappings = manifest.serverIslandMappings; -const driver = manifest.sessionDriver; -const mappings = await manifest.serverIslandMappings?.(); -const driver = await manifest.sessionDriver?.(); -``` - -Learn more about [the Adapter API](/en/reference/adapter-reference/). - -### Removed: `RouteData.generate()` - - - -The `generate()` method on `RouteData` has been removed. Route generation is now handled internally by Astro. - -#### What should I do? - -Remove any calls to `route.generate()` in your code. This method is no longer needed: - -```ts del={1} -const generated = route.generate(params); -``` - -Learn more about [routing](/en/guides/routing/). - -### Changed: Percent-Encoding Security Fix +### Vite Environment API -Routes with `%25` (percent-encoded percent sign) in filenames are no longer supported in static builds for security reasons. - -#### What should I do? - -If you have route files with `%25` in the filename, rename them to use a different character: - -```bash del={1} ins={2} -src/pages/test%25file.astro -src/pages/test-file.astro -``` - -This restriction prevents encoding-based security bypasses where `%25` decodes to `%`, potentially leading to ambiguous or invalid encoding sequences. - -### Removed: `astro:ssr-manifest` virtual module +Astro v6.0 introduces significant changes to how Astro manages different runtime environments (client, server, and prerender) after an internal refactor to use [Vite's new Environments API](https://vite.dev/guide/api-environment). - - -The `astro:ssr-manifest` virtual module has been removed entirely. It is no longer used by integrations or internally by Astro. +Integration and adapter maintainers should pay special attention to changes affecting these parts of the Integration API and Adapter API (full details included below with other breaking changes to these APIs): -#### What should I do? - -If your integration or code imports from `astro:ssr-manifest`, use `astro:config/server` instead to access configuration values: - -```ts del={1} ins={2,3} -import { manifest } from 'astro:ssr-manifest'; -import { srcDir, outDir, root } from 'astro:config/server'; -// Use srcDir, outDir, root, etc. for configuration values -``` - -The manifest is now passed directly through integration hooks and adapter APIs rather than through a virtual module. For build-specific manifest data, use the `astro:build:ssr` integration hook which receives the manifest as a parameter. - -Learn more about [the `astro:config` virtual module](/en/reference/modules/astro-config/). +- [integration hooks and HMR access patterns](#changed-integration-hooks-and-hmr-access-patterns-integration-api) +- [`SSRManifest` structure](#changed-ssrmanifest-interface-structure-adapter-api) +- [generating routes with `RouteData`](#removed-routedatagenerate-integration-api) +- [routes with percent-encoded percent signs (e.g. `%25`)](#removed-percent-encoding-in-routes) +- [astro:ssr-manifest` virtual module](#removed-astrossrmanifest-virtual-module-integration-api) ## Legacy @@ -509,6 +382,64 @@ You may also wish to consider using glob packages from NPM, such as [`fast-glob` Learn more about [importing files with `import.meta.glob`](/en/guides/imports/#importmetaglob). +### Removed: Percent-Encoding in routes + + + +In Astro 5.x, it was possible to include a percent-encoded percent sign (`%25`) in filenames. + +Astro 6.0 removes support for the characters `%25` in filenames for security reasons. This restriction prevents encoding-based security bypasses where `%25` decodes to `%`, potentially leading to ambiguous or invalid encoding sequences. + + +#### What should I do? + +If you have route files with `%25` in the filename, rename them to use a different character: + +```bash del={1} ins={2} +src/pages/test%25file.astro +src/pages/test-file.astro +``` + +### Removed: `astro:ssr-manifest` virtual module (Integration API) +{/* I can't find any record of this ever being documented anywhere in docs, but I am assuming it was deprecated at some point, and since it's removed, we don't need anyting in docs now */} + + + +In Astro 5.x, the deprecated `astro:ssr-manifest` virtual module could still be used to access configuration values. + +Astro 6.0 removes the `astro:ssr-manifest` virtual module entirely. It is no longer used by integrations or internally by Astro. The manifest is now passed directly through integration hooks and adapter APIs rather than through a virtual module. For build-specific manifest data, use the `astro:build:ssr` integration hook which receives the manifest as a parameter. + +#### What should I do? + +If your integration or code imports from `astro:ssr-manifest`, use `astro:config/server` instead to access configuration values: + +```ts del={1} ins={2,3} +import { manifest } from 'astro:ssr-manifest'; +import { srcDir, outDir, root } from 'astro:config/server'; +// Use srcDir, outDir, root, etc. for configuration values +``` + +Learn more about [the `astro:config` virtual module](/en/reference/modules/astro-config/). + +### Removed: `RouteData.generate()` (Integration API) + + + +In Astro 5.x, routes could be generated using the `generate()` method on `RouteData`. + +Astro 6.0 removes `RouteData.generate` because route generation is now handled internally by Astro. + +#### What should I do? + +Remove any calls to `route.generate()` in your code. This method is no longer needed: + +```ts del={1} +const generated = route.generate(params); +``` + +{/* I don't think we show anything like this on the routing page, so maybe linking to Integration API is better? */} +Learn more about [routing](/en/guides/routing/). + ### Removed: `routes` on `astro:build:done` hook (Integration API) @@ -1065,6 +996,97 @@ export function getStaticPaths() { Learn more about [dynamic SSG routes with `getStaticPaths()`](/en/guides/routing/#static-ssg-mode). +### Changed: Integration hooks and HMR access patterns (Integration API) + + + +In Astro 5.x, Astro relied on certain patterns for integration hooks and HMR access that were incompatible with or could be improved by integrating Vite's Environment API. + +Astro 6.0 uses Vite's new Environment API for build configuration and dev server interactions. This primarily enables dev mode in runtimes like workerd, but means that some integration hooks and HMR access patterns have changed. + +#### What should I do? + +**For integrations using `astro:build:setup`:** + +The hook is now called once with all environments, instead of being called separately for each build target. Remove the `target` parameter and use `vite.environments` to configure specific environments: + +```ts title="my-integration.mjs" del={3-7} ins={8-10} +{ + hooks: { + 'astro:build:setup': ({ target, vite }) => { + if (target === 'client') { + vite.build.minify = false; + } + } + 'astro:build:setup': ({ vite }) => { + vite.environments.client.build.minify = false; + } + } +} +``` + +**For dev toolbar and integration code accessing HMR:** + +Replace `server.hot.send()` with `server.environments.client.hot.send()`: + +```ts del={1} ins={2} +server.hot.send(event) +server.environments.client.hot.send(event) +``` + +Learn more about [Vite Environments API](https://vite.dev/guide/api-environment) and [integration hooks](/en/reference/integrations-reference/#astrobuildsetup). + +### Changed: `SSRManifest` interface structure (Adapter API) + + + +In Astro 5.x, path properties of the `SSRManifest` interface like `srcDir`, `outDir`, `cacheDir`, `publicDir`, `buildClientDir`, and `buildServerDir` were URL strings. + +Astro 6.0 changes the form of these path properties to `URL` objects instead of URL strings. With this change, several new properties are now available on the manifest. + +#### What should I do? + +If you were treating these path properties as strings, you'll now need to handle the `URL` object. For example, you will now need to access the `href` property of the `URL` object: + +```ts del={1} ins={2} +const srcPath = manifest.srcDir; // was a URL string like "file:///path/to/src" +const srcPath = manifest.srcDir; // now a URL object + +```ts del={2} ins={3} +// To retrieve the same format (e.g., "file:///path/to/src"), make the following change: +const srcPath = manifest.srcDir; +const srcPath = manifest.srcDir.href; +``` + +{/* These shouldn't be a breaking change, since they're new. But they should be documented in the appropriate API page if these are publicly available! */} + +{/* STUFF FOR REGULAR DOCS, PROBABLY?? +**New properties available:** + +The manifest now includes: +- `rootDir: URL` — Root directory of the project +- `assetsDir: string` — Directory containing built assets +- `serverLike: boolean` — Whether this is a server-like environment +- `logLevel: LoggerLevel` — Logging level + +**Removed `hrefRoot` property:** + +The `hrefRoot` property is no longer available on the manifest. + +**Async methods for dynamic data:** + +When accessing `serverIslandMappings` and `sessionDriver`, they are now async methods: + +```ts del={1,2} ins={3,4} +const mappings = manifest.serverIslandMappings; +const driver = manifest.sessionDriver; +const mappings = await manifest.serverIslandMappings?.(); +const driver = await manifest.sessionDriver?.(); +``` +*/} + +Learn more about [the Adapter API](/en/reference/adapter-reference/). + ## Community Resources Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below! From a938dd7c7836aecd6a2e5cf1e22db9e2d83a2ddc Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Mon, 1 Dec 2025 15:49:15 -0400 Subject: [PATCH 08/22] typo in anchor link --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index e820be143250e..dfa0be5704fb6 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -109,7 +109,7 @@ Integration and adapter maintainers should pay special attention to changes affe - [`SSRManifest` structure](#changed-ssrmanifest-interface-structure-adapter-api) - [generating routes with `RouteData`](#removed-routedatagenerate-integration-api) - [routes with percent-encoded percent signs (e.g. `%25`)](#removed-percent-encoding-in-routes) -- [astro:ssr-manifest` virtual module](#removed-astrossrmanifest-virtual-module-integration-api) +- [astro:ssr-manifest` virtual module](#removed-astrossr-manifest-virtual-module-integration-api) ## Legacy From 68308eb498eb562226f81648548c937174749134 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Mon, 1 Dec 2025 16:50:17 -0400 Subject: [PATCH 09/22] snagged some good info from the implementation PR changeset --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index dfa0be5704fb6..5fd310afec21d 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1008,7 +1008,7 @@ Astro 6.0 uses Vite's new Environment API for build configuration and dev server **For integrations using `astro:build:setup`:** -The hook is now called once with all environments, instead of being called separately for each build target. Remove the `target` parameter and use `vite.environments` to configure specific environments: +The hook is now called once with all environments configured (`ssr`, `client`, `prerender`), instead of being called separately for each build target. Remove the `target` parameter and use `vite.environments` to configure specific environments: ```ts title="my-integration.mjs" del={3-7} ins={8-10} { From 4d7a2ceb7434c8628eccc1fd8e7c33fd12a9701c Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 2 Dec 2025 17:22:40 -0500 Subject: [PATCH 10/22] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 72b49049d6083..53891aa115ddb 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1105,10 +1105,6 @@ Astro 6.0 changes the form of these path properties to `URL` objects instead of If you were treating these path properties as strings, you'll now need to handle the `URL` object. For example, you will now need to access the `href` property of the `URL` object: -```ts del={1} ins={2} -const srcPath = manifest.srcDir; // was a URL string like "file:///path/to/src" -const srcPath = manifest.srcDir; // now a URL object - ```ts del={2} ins={3} // To retrieve the same format (e.g., "file:///path/to/src"), make the following change: const srcPath = manifest.srcDir; From a94934a6651bcc1a297c0d4620dd2dab8c7ca2f9 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:01:25 -0400 Subject: [PATCH 11/22] remove code comment --- src/content/docs/en/guides/upgrade-to/v6.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 53891aa115ddb..306e715246a09 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -458,7 +458,6 @@ src/pages/test-file.astro ``` ### Removed: `astro:ssr-manifest` virtual module (Integration API) -{/* I can't find any record of this ever being documented anywhere in docs, but I am assuming it was deprecated at some point, and since it's removed, we don't need anyting in docs now */} From 18ed085ab4981da0424dc17e98906d3807738c7f Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:09:32 -0400 Subject: [PATCH 12/22] remove documentation for `target` --- .../en/reference/integrations-reference.mdx | 26 ------------------- 1 file changed, 26 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index effb14d6da7c6..d35874936fccf 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -73,7 +73,6 @@ interface AstroIntegration { 'astro:build:setup'?: (options: { vite: vite.InlineConfig; pages: Map; - target: 'client' | 'server'; updateConfig: (newConfig: vite.InlineConfig) => void; logger: AstroIntegrationLogger; }) => void | Promise; @@ -921,7 +920,6 @@ The address, family and port number supplied by the [Node.js Net module](https:/ 'astro:build:setup'?: (options: { vite: vite.InlineConfig; pages: Map; - target: 'client' | 'server'; updateConfig: (newConfig: vite.InlineConfig) => void; logger: AstroIntegrationLogger; }) => void | Promise; @@ -976,30 +974,6 @@ export default { } ``` -#### `target` option - -

- -**Type:** `'client' | 'server'` -

- -Builds are separated in two distinct phases: `client` and `server`. This option allow you to determine the current build phase. - -This can be used to perform an action only in a specific phase: - -```js -export default { - name: 'my-integration', - hooks: { - 'astro:build:setup': ({ target }) => { - if (target === "server") { - // do something in server build phase - } - }, - } -} -``` - #### `updateConfig()` option

From df744193b65d0da0afcbc5b791fc90a736a36ff3 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:29:26 -0400 Subject: [PATCH 13/22] update entry for manifest updates --- src/content/docs/en/guides/upgrade-to/v6.mdx | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 306e715246a09..22c3187bbcec9 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1110,24 +1110,10 @@ const srcPath = manifest.srcDir; const srcPath = manifest.srcDir.href; ``` -{/* These shouldn't be a breaking change, since they're new. But they should be documented in the appropriate API page if these are publicly available! */} -{/* STUFF FOR REGULAR DOCS, PROBABLY?? -**New properties available:** +If you were accessing the `hrefRoot` property, you will need to remove it as is no longer available on the manifest. -The manifest now includes: -- `rootDir: URL` — Root directory of the project -- `assetsDir: string` — Directory containing built assets -- `serverLike: boolean` — Whether this is a server-like environment -- `logLevel: LoggerLevel` — Logging level - -**Removed `hrefRoot` property:** - -The `hrefRoot` property is no longer available on the manifest. - -**Async methods for dynamic data:** - -When accessing `serverIslandMappings` and `sessionDriver`, they are now async methods: +Update any use of `serverIslandMappings` and `sessionDriver`, they are now async methods: ```ts del={1,2} ins={3,4} const mappings = manifest.serverIslandMappings; @@ -1135,7 +1121,6 @@ const driver = manifest.sessionDriver; const mappings = await manifest.serverIslandMappings?.(); const driver = await manifest.sessionDriver?.(); ``` -*/} Learn more about [the Adapter API](/en/reference/adapter-reference/). From c2676780feba52c4dcb8aa09d99436e18977e263 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:29:56 -0400 Subject: [PATCH 14/22] remove blank line --- src/content/docs/en/guides/upgrade-to/v6.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 22c3187bbcec9..57f68b5f87980 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1110,7 +1110,6 @@ const srcPath = manifest.srcDir; const srcPath = manifest.srcDir.href; ``` - If you were accessing the `hrefRoot` property, you will need to remove it as is no longer available on the manifest. Update any use of `serverIslandMappings` and `sessionDriver`, they are now async methods: From b49329a12d7a48ee9c6845da5150a9b91572c035 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:31:45 -0400 Subject: [PATCH 15/22] warn that other stuff changed too --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 57f68b5f87980..4bbf61a986ced 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1098,7 +1098,7 @@ server.environments.client.hot.send(event) In Astro 5.x, path properties of the `SSRManifest` interface like `srcDir`, `outDir`, `cacheDir`, `publicDir`, `buildClientDir`, and `buildServerDir` were URL strings. -Astro 6.0 changes the form of these path properties to `URL` objects instead of URL strings. With this change, several new properties are now available on the manifest. +Astro 6.0 changes the form of these path properties to `URL` objects instead of URL strings. With this change, several new properties are now available on the manifest and others have been updated or removed. #### What should I do? From e83f317d436635cb3fc0acd7411811129a03bb5e Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:41:07 -0400 Subject: [PATCH 16/22] RouteData change associated with Adapter API instead of Integration --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 4bbf61a986ced..dff46cfb8ddb8 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -477,7 +477,7 @@ import { srcDir, outDir, root } from 'astro:config/server'; Learn more about [the `astro:config` virtual module](/en/reference/modules/astro-config/). -### Removed: `RouteData.generate()` (Integration API) +### Removed: `RouteData.generate()` (Adapter API) From d1c447f67cf8944d2f9a553d3828e3e589c0a075 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:51:39 -0400 Subject: [PATCH 17/22] link to adapter API instead of routing guide --- src/content/docs/en/guides/upgrade-to/v6.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index dff46cfb8ddb8..3f061e45d597d 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -493,8 +493,7 @@ Remove any calls to `route.generate()` in your code. This method is no longer ne const generated = route.generate(params); ``` -{/* I don't think we show anything like this on the routing page, so maybe linking to Integration API is better? */} -Learn more about [routing](/en/guides/routing/). +Learn more about [the Adapter API](/en/reference/adapter-reference/). ### Removed: `routes` on `astro:build:done` hook (Integration API) From d097704eb28a4aeecefb5225a96e25f1633512c6 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 18:02:04 -0400 Subject: [PATCH 18/22] update line numbers in link to source code --- src/content/docs/en/reference/integrations-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index d35874936fccf..5dac13f2e507e 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -1023,7 +1023,7 @@ export default {

-**Type:** [`SerializedSSRManifest`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/core/app/types.ts#L91-L109) +**Type:** [`SerializedSSRManifest`](https://github.com/withastro/astro/blob/95a1969a05cc9c15f16dcf2177532882bb392581/packages/astro/src/core/app/types.ts#L126-L144)

Allows you to create a custom build by accessing the SSR manifest. From 6e4192899f5b4a7c73e852367f8aa9e175307b76 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 18:07:29 -0400 Subject: [PATCH 19/22] remove blank line --- src/content/docs/en/guides/upgrade-to/v6.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 3f061e45d597d..e0616a95b8fcd 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -447,7 +447,6 @@ In Astro 5.x, it was possible to include a percent-encoded percent sign (`%25`) Astro 6.0 removes support for the characters `%25` in filenames for security reasons. This restriction prevents encoding-based security bypasses where `%25` decodes to `%`, potentially leading to ambiguous or invalid encoding sequences. - #### What should I do? If you have route files with `%25` in the filename, rename them to use a different character: From b0fad876fe995fe548383f8aec74b13edd1f3587 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 18:22:55 -0400 Subject: [PATCH 20/22] polishing nits --- src/content/docs/en/guides/upgrade-to/v6.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 263b681c112e5..8232a7363070a 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -107,9 +107,9 @@ Integration and adapter maintainers should pay special attention to changes affe - [integration hooks and HMR access patterns](#changed-integration-hooks-and-hmr-access-patterns-integration-api) - [`SSRManifest` structure](#changed-ssrmanifest-interface-structure-adapter-api) -- [generating routes with `RouteData`](#removed-routedatagenerate-integration-api) +- [generating routes with `RouteData`](#removed-routedatagenerate-adapter-api) - [routes with percent-encoded percent signs (e.g. `%25`)](#removed-percent-encoding-in-routes) -- [astro:ssr-manifest` virtual module](#removed-astrossr-manifest-virtual-module-integration-api) +- [`astro:ssr-manifest` virtual module](#removed-astrossr-manifest-virtual-module-integration-api) ## Legacy @@ -1115,7 +1115,7 @@ server.hot.send(event) server.environments.client.hot.send(event) ``` -Learn more about [Vite Environments API](https://vite.dev/guide/api-environment) and [integration hooks](/en/reference/integrations-reference/#astrobuildsetup). +Learn more about the [Vite Environment API](https://vite.dev/guide/api-environment) and Astro [integration hooks](/en/reference/integrations-reference/#astrobuildsetup). ### Changed: `SSRManifest` interface structure (Adapter API) @@ -1127,7 +1127,7 @@ Astro 6.0 changes the form of these path properties to `URL` objects instead of #### What should I do? -If you were treating these path properties as strings, you'll now need to handle the `URL` object. For example, you will now need to access the `href` property of the `URL` object: +If you were treating these path properties as strings, you will now need to handle the `URL` object. For example, you will now need to access the `href` property of the `URL` object: ```ts del={2} ins={3} // To retrieve the same format (e.g., "file:///path/to/src"), make the following change: @@ -1137,7 +1137,7 @@ const srcPath = manifest.srcDir.href; If you were accessing the `hrefRoot` property, you will need to remove it as is no longer available on the manifest. -Update any use of `serverIslandMappings` and `sessionDriver`, they are now async methods: +Update any use of `serverIslandMappings` and `sessionDriver`. These are now async methods: ```ts del={1,2} ins={3,4} const mappings = manifest.serverIslandMappings; From 3401d6d684a4bf3b8ddd5c3d1cb7e35af42d9279 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 3 Dec 2025 18:50:02 -0400 Subject: [PATCH 21/22] fix missing function notation Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 8232a7363070a..12b53bc417974 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -509,7 +509,7 @@ import { srcDir, outDir, root } from 'astro:config/server'; In Astro 5.x, routes could be generated using the `generate()` method on `RouteData`. -Astro 6.0 removes `RouteData.generate` because route generation is now handled internally by Astro. +Astro 6.0 removes `RouteData.generate()` because route generation is now handled internally by Astro. #### What should I do? From b0b4b494270ea0b5f3ff6f7e608afe3497fe1e47 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:12:39 -0400 Subject: [PATCH 22/22] Yan final boss review Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/en/guides/upgrade-to/v6.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 12b53bc417974..2b44330b3724c 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -489,7 +489,7 @@ src/pages/test-file.astro In Astro 5.x, the deprecated `astro:ssr-manifest` virtual module could still be used to access configuration values. -Astro 6.0 removes the `astro:ssr-manifest` virtual module entirely. It is no longer used by integrations or internally by Astro. The manifest is now passed directly through integration hooks and adapter APIs rather than through a virtual module. For build-specific manifest data, use the `astro:build:ssr` integration hook which receives the manifest as a parameter. +Astro 6.0 removes the `astro:ssr-manifest` virtual module entirely. It is no longer used by integrations or internally by Astro. The manifest is now passed directly through integration hooks and adapter APIs rather than through a virtual module. For build-specific manifest data, use the `astro:build:ssr` integration hook, which receives the manifest as a parameter. #### What should I do? @@ -1123,7 +1123,7 @@ server.environments.client.hot.send(event) In Astro 5.x, path properties of the `SSRManifest` interface like `srcDir`, `outDir`, `cacheDir`, `publicDir`, `buildClientDir`, and `buildServerDir` were URL strings. -Astro 6.0 changes the form of these path properties to `URL` objects instead of URL strings. With this change, several new properties are now available on the manifest and others have been updated or removed. +Astro 6.0 changes the form of these path properties to `URL` objects instead of URL strings. With this change, several new properties are now available on the manifest, and others have been updated or removed. #### What should I do? @@ -1135,7 +1135,7 @@ const srcPath = manifest.srcDir; const srcPath = manifest.srcDir.href; ``` -If you were accessing the `hrefRoot` property, you will need to remove it as is no longer available on the manifest. +If you were accessing the `hrefRoot` property, you will need to remove it, as it is no longer available on the manifest. Update any use of `serverIslandMappings` and `sessionDriver`. These are now async methods: