feat(core): add routePattern to GetStaticPathsOptions (#13520)

openscript · sarah11918 · florian-lefebvre · web-flow · commit a31edb8daad8 · 2025-09-24T16:00:46.000+01:00
* feat: add `routePattern` to `GetStaticPathsOptions`

* chore: add changeset

* chore: test `routePattern` in `getStaticPaths()`

* chore: enhance test

* fill out changeset with hype!

---------

Co-authored-by: Sarah Rainsberger &lt;5098874+sarah11918@users.noreply.github.com&gt;
Co-authored-by: Florian Lefebvre &lt;contact@florian-lefebvre.dev&gt;
diff --git a/.changeset/little-sheep-hear.md b/.changeset/little-sheep-hear.md
@@ -0,0 +1,27 @@
+---
+'astro': minor
+---
+
+Adds a new property `routePattern` available to `GetStaticPathsOptions`
+
+This provides the original, dynamic segment definition in a routing file path (e.g. `/[...locale]/[files]/[slug]`) from the Astro render context that would not otherwise be available within the scope of `getStaticPaths()`. This can be useful to calculate the `params` and `props` for each page route.
+
+For example, you can now localize your route segments and return an array of static paths by passing `routePattern` to a custom `getLocalizedData()` helper function. The `params` object will be set with explicit values for each route segment (e.g. `locale`, `files`, and `slug)`. Then, these values will be used to generate the routes and can be used in your page template via `Astro.params`.
+
+
+```astro
+// src/pages/[...locale]/[files]/[slug].astro
+---
+import { getLocalizedData } from "../../../utils/i18n";
+export async function getStaticPaths({ routePattern }) {
+  const response = await fetch('...');
+  const data = await response.json();
+  console.log(routePattern); // [...locale]/[files]/[slug]
+  // Call your custom helper with `routePattern` to generate the static paths
+  return data.flatMap((file) => getLocalizedData(file, routePattern));
+}
+const { locale, files, slug } = Astro.params;
+---
+```
+
+For more information about this advanced routing pattern, see Astro's [routing reference](https://docs.astro.build/en/reference/routing-reference/#routepattern).
diff --git a/packages/astro/src/core/render/route-cache.ts b/packages/astro/src/core/render/route-cache.ts
@@ -60,6 +60,7 @@ export async function callGetStaticPaths({
 		// Q: Why the cast?
 		// A: So users downstream can have nicer typings, we have to make some sacrifice in our internal typings, which necessitate a cast here
 		paginate: generatePaginateFunction(route, base) as PaginateFunction,
+		routePattern: route.route,
 	});
 
 	validateGetStaticPathsResult(staticPaths, logger, route);
diff --git a/packages/astro/src/types/public/common.ts b/packages/astro/src/types/public/common.ts
@@ -9,6 +9,7 @@ import type { APIContext } from './context.js';
  */
 export interface GetStaticPathsOptions {
 	paginate: PaginateFunction;
+	routePattern: string;
 }
 
 export type GetStaticPathsItem = {
diff --git a/packages/astro/test/astro-get-static-paths.test.js b/packages/astro/test/astro-get-static-paths.test.js
@@ -103,6 +103,16 @@ describe('getStaticPaths - dev calls', () => {
 		});
 	});
 
+	it('provides routePattern', async () => {
+		const res = await fixture.fetch('/blog/2022/post-1');
+		assert.equal(res.status, 200);
+
+		const html = await res.text();
+		const $ = cheerio.load(html);
+
+		assert.equal($('#route-pattern').text(), '/blog/[year]/[slug]');
+	});
+
 	it('resolves 200 on matching static paths', async () => {
 		// routes params provided for pages /posts/1, /posts/2, and /posts/3
 		for (const page of [1, 2, 3]) {
diff --git a/packages/astro/test/fixtures/astro-get-static-paths/src/pages/blog/[year]/[slug].astro b/packages/astro/test/fixtures/astro-get-static-paths/src/pages/blog/[year]/[slug].astro
@@ -1,18 +1,21 @@
 ---
-export async function getStaticPaths() {
-    return [
-        { params: { year: '2022', slug: 'post-1' } },
-        { params: { year: 2022, slug: 'post-2' } },
-        { params: { slug: 'post-2', year: '2022' } },
-    ]
+export async function getStaticPaths({ routePattern }) {
+	return [
+		{ params: { year: '2022', slug: 'post-1' }, props: { routePattern } },
+		{ params: { year: 2022, slug: 'post-2' }, props: { routePattern } },
+		{ params: { slug: 'post-2', year: '2022' }, props: { routePattern } },
+	]
 }
 
 const { year, slug } = Astro.params
+const { routePattern } = Astro.props
 ---
 
 <html>
-  <head>
-    <title>{year} | {slug}</title>
-  </head>
-  <body></body>
+	<head>
+		<title>{year} | {slug}</title>
+	</head>
+	<body>
+		<p id="route-pattern">{routePattern}</p>
+	</body>
 </html>

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@ import type { APIContext } from './context.js';`
`9`	`9`	`*/`
`10`	`10`	`export interface GetStaticPathsOptions {`
`11`	`11`	`paginate: PaginateFunction;`
	`12`	`+ routePattern: string;`
`12`	`13`	`}`
`13`	`14`
`14`	`15`	`export type GetStaticPathsItem = {`