From 4c684603d017b185a8d3c59ccafa114456863dbf Mon Sep 17 00:00:00 2001 From: Prayaksh Date: Sun, 17 May 2026 12:22:01 +0000 Subject: [PATCH 1/5] docs: clarify Astro.url and Astro.params runtime behavior --- src/content/docs/en/guides/upgrade-to/v6.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 1b1a284c6dffc..2a99d9bab3b01 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -832,6 +832,13 @@ If you have route files with `%25` in the filename, rename them to use a differe src/pages/test%25file.astro src/pages/test-file.astro ``` +Astro v6 also changed how URLs and route parameters are handled at runtime. + +`Astro.url` returns a normalized and partially decoded URL, so it may differ from `new URL(Astro.request.url)`. + +`Astro.params` values are automatically decoded, and percent-encoded characters in pathnames or parameters (like `%25`) may appear decoded in `Astro.url` or `Astro.params`. + +If you need the raw request URL with no decoding, use `Astro.request.url` and parse it manually. ### Removed: `astro:ssr-manifest` virtual module (Integration API) From 4a89ecd849c02e65d275a636e95b307b95ae4e2d Mon Sep 17 00:00:00 2001 From: Prayaksh Date: Sat, 23 May 2026 12:49:39 +0000 Subject: [PATCH 2/5] docs: clarify Astro.url and params normalization --- src/content/docs/en/reference/api-reference.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index df1dc39c77d6c..ac38ba8cd605b 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -137,6 +137,8 @@ In static builds, this will be the `params` returned by `getStaticPaths()` used When routes are rendered on demand, `params` can be any value matching the path segments in the dynamic route pattern. +`params` values are automatically decoded from route pathnames. + ```astro title="src/pages/posts/[id].astro" "Astro.params" --- import { getPost } from '../api'; @@ -165,7 +167,9 @@ See also: [`params`](/en/reference/routing-reference/#params) `url` is a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `request.url` value. It is useful for interacting with individual properties of the request URL, like pathname and origin. -`Astro.url` is equivalent to doing `new URL(Astro.request.url)`. +`Astro.url` is a normalized `URL` instance derived from `Astro.request.url`. + +In Astro v6, the pathname is partially decoded during route normalization, so `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. `url` will be a `localhost` URL in dev mode. When building a site, prerendered routes will receive a URL based on the [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options. If `site` is not configured, prerendered pages will receive a `localhost` URL during builds as well. From 16481eae6b4197ddc1b3772abc6dcd3401bf20ff Mon Sep 17 00:00:00 2001 From: Prayaksh Date: Sat, 30 May 2026 05:47:50 +0000 Subject: [PATCH 3/5] docs: clarify route pathname normalization --- src/content/docs/en/guides/upgrade-to/v6.mdx | 18 ++++++++++++------ .../docs/en/reference/api-reference.mdx | 8 ++------ 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 2a99d9bab3b01..57cfe9778464f 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -832,13 +832,7 @@ If you have route files with `%25` in the filename, rename them to use a differe src/pages/test%25file.astro src/pages/test-file.astro ``` -Astro v6 also changed how URLs and route parameters are handled at runtime. -`Astro.url` returns a normalized and partially decoded URL, so it may differ from `new URL(Astro.request.url)`. - -`Astro.params` values are automatically decoded, and percent-encoded characters in pathnames or parameters (like `%25`) may appear decoded in `Astro.url` or `Astro.params`. - -If you need the raw request URL with no decoding, use `Astro.request.url` and parse it manually. ### Removed: `astro:ssr-manifest` virtual module (Integration API) @@ -1578,6 +1572,18 @@ If you want to keep the old ID generation for backward compatibility reasons, yo Learn more about [Heading IDs](/en/guides/markdown-content/#heading-ids). +### Changed: Route pathname normalization + + + +Since Astro v6, route pathnames are partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. + +This also affects route params derived from normalized pathnames. + +#### What should I do? + +If you need access to the original encoded pathname, use `new URL(Astro.request.url).pathname` instead of `Astro.url.pathname`. + ### Changed: `getStaticPaths()` cannot return `params` of type number diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index ac38ba8cd605b..309b6cfd6acb0 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -137,8 +137,6 @@ In static builds, this will be the `params` returned by `getStaticPaths()` used When routes are rendered on demand, `params` can be any value matching the path segments in the dynamic route pattern. -`params` values are automatically decoded from route pathnames. - ```astro title="src/pages/posts/[id].astro" "Astro.params" --- import { getPost } from '../api'; @@ -165,11 +163,9 @@ See also: [`params`](/en/reference/routing-reference/#params)

-`url` is a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object constructed from the current `request.url` value. It is useful for interacting with individual properties of the request URL, like pathname and origin. - -`Astro.url` is a normalized `URL` instance derived from `Astro.request.url`. +A normalized [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object derived from the current `request.url` value. It is useful for interacting with individual properties of the request URL, like pathname and origin. -In Astro v6, the pathname is partially decoded during route normalization, so `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. +Since Astro v6, the pathname may be partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. `url` will be a `localhost` URL in dev mode. When building a site, prerendered routes will receive a URL based on the [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options. If `site` is not configured, prerendered pages will receive a `localhost` URL during builds as well. From 78e6442a16e4e51f77a4ebf06d40ac9dc6d3da6a Mon Sep 17 00:00:00 2001 From: Prayaksh Upadhyay Date: Wed, 3 Jun 2026 09:58:03 +0530 Subject: [PATCH 4/5] Update src/content/docs/en/guides/upgrade-to/v6.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/upgrade-to/v6.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 57cfe9778464f..e35cd32a7e7e1 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1584,6 +1584,16 @@ This also affects route params derived from normalized pathnames. If you need access to the original encoded pathname, use `new URL(Astro.request.url).pathname` instead of `Astro.url.pathname`. +If you were previously relying on the automatic decoding, use [`decodeURI()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI): + +```astro title="src/pages/[slug].astro" +--- +const decodedPathname = decodeURI(Astro.url.pathname); +--- + +

You are currently browsing: {decodedPathname}

+``` + ### Changed: `getStaticPaths()` cannot return `params` of type number From aeb1b2e88bc1950ac9d9a8eccaa2b3cb1d10d7dd Mon Sep 17 00:00:00 2001 From: Prayaksh Upadhyay Date: Wed, 3 Jun 2026 09:58:24 +0530 Subject: [PATCH 5/5] Update src/content/docs/en/reference/api-reference.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/reference/api-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 309b6cfd6acb0..aae51e9f5da79 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -165,7 +165,7 @@ See also: [`params`](/en/reference/routing-reference/#params) A normalized [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object derived from the current `request.url` value. It is useful for interacting with individual properties of the request URL, like pathname and origin. -Since Astro v6, the pathname may be partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments. +Since Astro v6, the pathname may be partially decoded during route normalization. This means `Astro.url.pathname` may differ from `new URL(Astro.request.url).pathname` for percent-encoded route segments, and you may need to decode it yourself with [`decodeURI()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI). `url` will be a `localhost` URL in dev mode. When building a site, prerendered routes will receive a URL based on the [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options. If `site` is not configured, prerendered pages will receive a `localhost` URL during builds as well.