Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Pages, Layouts and Routing

Dynamic Routes and getStaticPaths

Generate many pages from one file with dynamic routes. Learn [param] and [...rest] syntax, getStaticPaths, props, nested params and on-demand routes.

Writing one file per page does not scale when you have a hundred blog posts or a thousand products. A dynamic route is one file that produces many pages. Its file name contains a parameter in square brackets, such as [slug].astro, and Astro fills the parameter with a different value for each page.

For a static site, Astro must know every value at build time, because it writes one HTML file per page. You tell it by exporting a function named getStaticPaths.

A first dynamic route

Create src/pages/fruits/[name].astro:

ASTRO
---
export function getStaticPaths() {
  return [
    { params: { name: "apple" } },
    { params: { name: "pear" } },
    { params: { name: "plum" } },
  ];
}

const { name } = Astro.params;
---
<h1>Fruit: {name}</h1>

The build writes three pages: /fruits/apple, /fruits/pear and /fruits/plum. Inside the page, Astro.params holds the values for the page being rendered.

One file, many pages

[name].astro A pattern
getStaticPaths Lists every value
1 / 2

Passing data with props

Each entry can carry props, which are available in Astro.props. This avoids fetching the same data twice, once to list the paths and again inside the page:

ASTRO
---
export async function getStaticPaths() {
  const response = await fetch("https://api.example.com/products");
  const products = await response.json();

  return products.map((product) => ({
    params: { id: String(product.id) },
    props: { product },
  }));
}

const { product } = Astro.props;
---
<h1>{product.name}</h1>
<p>{product.price} USD</p>

Remember that params values are strings (or undefined for optional segments), while props can be any value. Code in getStaticPaths runs in isolation before the page, so it cannot use variables from the component script; define helpers inside the function or import them.

Several parameters

A file may have more than one bracket, either as separate segments or in one segment:

TEXT
src/pages/[lang]/blog/[slug].astro     -> /en/blog/hello, /fr/blog/bonjour
src/pages/[category]-[id].astro        -> /shoes-42

Every path object must then supply every parameter:

ASTRO
---
export function getStaticPaths() {
  return [
    { params: { lang: "en", slug: "hello" } },
    { params: { lang: "fr", slug: "bonjour" } },
  ];
}
---

Rest parameters

A rest parameter, written [...path], matches one or more segments, including none if you set it to undefined. Documentation sites use it for nested trees:

ASTRO
---
// src/pages/docs/[...path].astro
export function getStaticPaths() {
  return [
    { params: { path: undefined } },        // /docs
    { params: { path: "intro" } },          // /docs/intro
    { params: { path: "guides/install" } }, // /docs/guides/install
  ];
}
const { path } = Astro.params;
---
<h1>Docs: {path ?? "home"}</h1>

Dynamic routes with collections

The most common use is building a page per entry of a content collection. This previews a later lesson on querying collections:

ASTRO
---
import { getCollection, render } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => ({
    params: { slug: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await render(post);
---
<h1>{post.data.title}</h1>
<Content />

On-demand rendering

With server output you may not know the values ahead of time, for example /users/123 where any id is valid. A server-rendered dynamic route does not need getStaticPaths; it reads Astro.params for each request. That topic belongs to the SSR chapter.

Stand-in: expanding a route pattern

The build step expands a pattern with a list of params into concrete URLs, and the router later matches an incoming URL back to a pattern. This stand-in does both.

Node.js Stand-in: getStaticPaths expansion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: matching a URL to a route

Matching goes the other way. The stand-in converts a pattern to a regular expression, extracts params and applies the static-before-dynamic priority from the routing lesson.

Node.js Stand-in: match a URL against patterns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Errors you will see

  • "Missing parameter": a path object leaves out a parameter the file name requires.
  • "getStaticPaths() function is required": a static build found a dynamic file without the function.
  • Duplicate routes: two path objects produce the same URL.
  • Params must be strings: pass String(id) for numbers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a static build need getStaticPaths for a [slug].astro page?

    A static site writes one file per page, so Astro needs the full list of parameter values ahead of time.
  2. 2. How do you hand a fetched object to the page so it does not need fetching again?

    props from getStaticPaths show up in Astro.props. params become part of the URL.
  3. 3. What does [...path] match?

    Rest parameters match nested paths such as guides/install, or nothing if set to undefined.
  4. 4. Which type must params values be?

    URL pieces are strings, so convert numbers with String(). Rest params may be undefined.

Summary

  • A bracketed file name such as [slug].astro is a dynamic route that creates many pages.
  • Static builds export getStaticPaths returning { params, props } objects.
  • Astro.params gives URL values; Astro.props carries any data you attach.
  • Rest parameters ([...path]) match nested paths; routes can have several parameters.
  • Server-rendered routes can read params per request without getStaticPaths.

Next: Pagination