From ce89532c21156960e9bd0bffc3ba3a77be62cedb Mon Sep 17 00:00:00 2001
From: Emanuele Stoppa <my.burning@gmail.com>
Date: Thu, 3 Oct 2024 14:54:23 +0100
Subject: [PATCH] feat: document decoding of params (#9497)

* feat: document decoding of params

* update migration

* move content on routing page to SSG section

* edit upgrade guide entry

---------

Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
Co-authored-by: sarahrainsberger <sarahrainsberger@gmail.com>
---
 src/content/docs/en/guides/routing.mdx       | 15 +++++++++-
 src/content/docs/en/guides/upgrade-to/v5.mdx | 30 ++++++++++++++++++++
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/en/guides/routing.mdx b/src/content/docs/en/guides/routing.mdx
index e1fafb49de1bc..0821fbd946e85 100644
--- a/src/content/docs/en/guides/routing.mdx
+++ b/src/content/docs/en/guides/routing.mdx
@@ -87,8 +87,21 @@ This will generate `/en-v1/info` and `/fr-v2/info`.
 
 Parameters can be included in separate parts of the path. For example, the file `src/pages/[lang]/[version]/info.astro` with the same `getStaticPaths()` above will generate the routes `/en/v1/info` and `/fr/v2/info`.
 
-<ReadMore>Learn more about [`getStaticPaths()`](/en/reference/api-reference/#getstaticpaths).</ReadMore>
+#### Decoding `params`
+
+The `params` provided to the function `getStaticPaths()` function are not decoded. Use the function [`decodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) when you need to decode parameter values.
+
+```astro title="src/pages/[slug].astro"
+--- 
+export function getStaticPaths() {
+  return [
+    { params: { slug: decodeURI("%5Bpage%5D") } }, // decodes to "[page]"
+  ]
+}
+---
+```
 
+<ReadMore>Learn more about [`getStaticPaths()`](/en/reference/api-reference/#getstaticpaths).</ReadMore>
 
 <RecipeLinks slugs={["en/recipes/i18n"]} />
 
diff --git a/src/content/docs/en/guides/upgrade-to/v5.mdx b/src/content/docs/en/guides/upgrade-to/v5.mdx
index 434ce34269e93..c6a42e4c1f681 100644
--- a/src/content/docs/en/guides/upgrade-to/v5.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v5.mdx
@@ -928,6 +928,36 @@ Object.assign(ctx.locals, {
 ```
 <ReadMore>See more about [storing data in `context.locals`](/en/guides/middleware/#storing-data-in-contextlocals).</ReadMore>
 
+### Changed: `params` no longer decoded
+
+<SourcePR number="12079" title="decode pathname early, don't decode params"/>
+
+In Astro v4.x, `params` passed to `getStaticPath()` were automatically decoded using `decodeURIComponent`.
+
+Astro v5.0 no longer decodes the value of `params` passed to `getStaticPaths`. You must manually decode them yourself if needed.
+
+#### What should I do?
+
+If you were previously relying on the automatic decoding, use `decodeURI` when passing `params`.
+
+
+```astro title="src/pages/[id].astro" del={4} ins={5}
+---
+export function getStaticPaths() {
+  return [
+    { params: { id: "%5Bpage%5D" } },
+    { params: { id: decodeURI("%5Bpage%5D") } },
+  ]
+}
+
+const { id } = Astro.params;
+---
+```
+
+Note that the use of [`decodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent)) is discouraged for `getStaticPaths` because it decodes more characters than it should, for example `/`, `?`, `#` and more.
+
+<ReadMore>Read more about [creating dynamic routes with `params`](/en/guides/routing/#static-ssg-mode).</ReadMore>
+
 ### Changed: `RouteData` type replaced by `IntegrationsRouteData` (Integrations API)
 
 <SourcePR number="11864" title="send `IntegrationRouteData` to integrations"/>