generateStaticParams: Pre-building Dynamic Pages in Next.js

Why it exists

When you build a site for production, Next.js can pre-render pages as static HTML. For a dynamic route like /blog/[slug], Next.js doesn't know what all the possible slugs are. generateStaticParams was created to solve this by explicitly telling Next.js which pages to generate at build time.

The mental model

Imagine you're a printer tasked with creating personalized invitations. generateStaticParams is the spreadsheet you're given with everyone's name on it. Instead of waiting for someone to request an invitation for 'Alice' and then 'Bob', you get the entire guest list upfront and can print all the invitations in one efficient batch. The function provides the list of pages to build; it doesn't write the content of the invitation itself.

How it works

In a dynamic route segment's page.js or layout.js file (e.g., app/products/[id]/page.js), you export an async function called generateStaticParams. This function fetches data and must return an array of objects, where each object represents one page to be generated. For the product example, it would return [{ id: '1' }, { id: '2' }, { id: '3' }]. Next.js then iterates through this array, building a static page for /products/1, /products/2, and /products/3.

When to use it

Use generateStaticParams in the App Router for any dynamic route you want to statically generate (SSG). This is ideal for content that doesn't change frequently, like blog posts, e-commerce product pages, or documentation sites. It results in extremely fast page loads because the HTML is pre-built and served from a CDN.

When not to use it

Do not use this for pages that require fresh data on every request, like a user's account dashboard; use dynamic rendering (SSR) instead. Also, avoid it if the number of possible parameters is enormous (e.g., millions of user profiles), as this would make the build process impossibly long. In such cases, you can let pages be generated on-demand.

One canonical example

For a blog at /posts/[slug], you would define generateStaticParams in app/posts/[slug]/page.js. The function would fetch all post slugs from your database or CMS and return [{ slug: 'intro-to-react' }, { slug: 'advanced-css-tricks' }]. Then, the Page component in that same file would receive params.slug and use it to fetch the full content for that specific post. The key is that generateStaticParams provides the 'what' (which pages), while the Page component handles the 'how' (fetching and rendering the content).