f0df2c274d
In `Generating paths on-demand` section It was mentioned that `getStaticProps` allows you to control which pages are generated during the build. But `getStaticPaths` will allows us to control which pages are generated during the build. ## Bug - [ ] Related issues linked using `fixes #number` - [ ] Integration tests added - [ ] Errors have helpful link attached, see `contributing.md` ## Feature - [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [ ] Related issues linked using `fixes #number` - [ ] Integration tests added - [ ] Documentation added - [ ] Telemetry added. In case of a feature if it's used or not. - [ ] Errors have helpful link attached, see `contributing.md` ## Documentation / Examples - [ ] Make sure the linting passes by running `pnpm lint` - [ ] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
---
|
||
description: Fetch data and generate static pages with `getStaticProps`. Learn more about this API for data fetching in Next.js.
|
||
---
|
||
|
||
# getStaticPaths
|
||
|
||
If a page has [Dynamic Routes](/docs/routing/dynamic-routes.md) and uses `getStaticProps`, it needs to define a list of paths to be statically generated.
|
||
|
||
When you export a function called `getStaticPaths` (Static Site Generation) from a page that uses dynamic routes, Next.js will statically pre-render all the paths specified by `getStaticPaths`.
|
||
|
||
```jsx
|
||
// pages/posts/[id].js
|
||
|
||
// Generates `/posts/1` and `/posts/2`
|
||
export async function getStaticPaths() {
|
||
return {
|
||
paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
|
||
fallback: false, // can also be true or 'blocking'
|
||
}
|
||
}
|
||
|
||
// `getStaticPaths` requires using `getStaticProps`
|
||
export async function getStaticProps(context) {
|
||
return {
|
||
// Passed to the page component as props
|
||
props: { post: {} },
|
||
}
|
||
}
|
||
|
||
export default function Post({ post }) {
|
||
// Render post...
|
||
}
|
||
```
|
||
|
||
The [`getStaticPaths` API reference](/docs/api-reference/data-fetching/get-static-paths.md) covers all parameters and props that can be used with `getStaticPaths`.
|
||
|
||
## When should I use getStaticPaths?
|
||
|
||
You should use `getStaticPaths` if you’re statically pre-rendering pages that use dynamic routes and:
|
||
|
||
- The data comes from a headless CMS
|
||
- The data comes from a database
|
||
- The data comes from the filesystem
|
||
- The data can be publicly cached (not user-specific)
|
||
- The page must be pre-rendered (for SEO) and be very fast — `getStaticProps` generates `HTML` and `JSON` files, both of which can be cached by a CDN for performance
|
||
|
||
## When does getStaticPaths run
|
||
|
||
`getStaticPaths` will only run during build in production, it will not be called during runtime. You can validate code written inside `getStaticPaths` is removed from the client-side bundle [with this tool](https://next-code-elimination.vercel.app/).
|
||
|
||
### How does getStaticProps run with regards to getStaticPaths
|
||
|
||
- `getStaticProps` runs during `next build` for any `paths` returned during build
|
||
- `getStaticProps` runs in the background when using `fallback: true`
|
||
- `getStaticProps` is called before initial render when using `fallback: blocking`
|
||
|
||
## Where can I use getStaticPaths
|
||
|
||
- `getStaticPaths` **must** be used with `getStaticProps`
|
||
- You **cannot** use `getStaticPaths` with [`getServerSideProps`](/docs/basic-features/data-fetching/get-server-side-props.md)
|
||
- You can export `getStaticPaths` from a [Dynamic Route](/docs/routing/dynamic-routes.md) that also uses `getStaticProps`
|
||
- You **cannot** export `getStaticPaths` from non-page file (e.g. your `components` folder)
|
||
- You must export `getStaticPaths` as a standalone function, and not a property of the page component
|
||
|
||
## Runs on every request in development
|
||
|
||
In development (`next dev`), `getStaticPaths` will be called on every request.
|
||
|
||
## Generating paths on-demand
|
||
|
||
`getStaticPaths` allows you to control which pages are generated during the build instead of on-demand with [`fallback`](/docs/api-reference/data-fetching/get-static-paths.md#fallback-blocking). Generating more pages during a build will cause slower builds.
|
||
|
||
You can defer generating all pages on-demand by returning an empty array for `paths`. This can be especially helpful when deploying your Next.js application to multiple environments. For example, you can have faster builds by generating all pages on-demand for previews (but not production builds). This is helpful for sites with hundreds/thousands of static pages.
|
||
|
||
```jsx
|
||
// pages/posts/[id].js
|
||
|
||
export async function getStaticPaths() {
|
||
// When this is true (in preview environments) don't
|
||
// prerender any static pages
|
||
// (faster builds, but slower initial page load)
|
||
if (process.env.SKIP_BUILD_STATIC_GENERATION) {
|
||
return {
|
||
paths: [],
|
||
fallback: 'blocking',
|
||
}
|
||
}
|
||
|
||
// Call an external API endpoint to get posts
|
||
const res = await fetch('https://.../posts')
|
||
const posts = await res.json()
|
||
|
||
// Get the paths we want to prerender based on posts
|
||
// In production environments, prerender all pages
|
||
// (slower builds, but faster initial page load)
|
||
const paths = posts.map((post) => ({
|
||
params: { id: post.id },
|
||
}))
|
||
|
||
// { fallback: false } means other routes should 404
|
||
return { paths, fallback: false }
|
||
}
|
||
```
|
||
|
||
## Related
|
||
|
||
For more information on what to do next, we recommend the following sections:
|
||
|
||
<div class="card">
|
||
<a href="/docs/api-reference/data-fetching/get-static-paths.md">
|
||
<b>getStaticPaths API Reference</b>
|
||
<small>Read the API Reference for getStaticPaths</small>
|
||
</a>
|
||
</div>
|