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 <[email protected]> Co-authored-by: sarahrainsberger <[email protected]>
withastro · Oct 3, 2024 · ce89532 · ce89532
1 parent 12d8dfd
commit ce89532
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 1 deletion.
diff --git 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
@@ -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"/>