getStaticProps
Exporting a function called getStaticProps
will pre-render a page at build time using the props returned from the function:
You can import modules in top-level scope for use in getStaticProps
. Imports used will not be bundled for the client-side. This means you can write server-side code directly in getStaticProps
, including fetching data from your database.
Context parameter
The context
parameter is an object containing the following keys:
Name | Description |
---|---|
params | Contains the route parameters for pages using dynamic routes. For example, if the page name is [id].js , then params will look like { id: ... } . You should use this together with getStaticPaths , which we'll explain later. |
preview | (Deprecated for draftMode ) preview is true if the page is in the Preview Mode and false otherwise. |
previewData | (Deprecated for draftMode ) The preview data set by setPreviewData . |
draftMode | draftMode is true if the page is in the Draft Mode and false otherwise. |
locale | Contains the active locale (if enabled). |
locales | Contains all supported locales (if enabled). |
defaultLocale | Contains the configured default locale (if enabled). |
revalidateReason | Provides a reason for why the function was called. Can be one of: "build" (run at build time), "stale" (revalidate period expired, or running in development mode), "on-demand" (triggered via on-demand revalidation) |
getStaticProps return values
The getStaticProps
function should return an object containing either props
, redirect
, or notFound
followed by an optional revalidate
property.
props
The props
object is a key-value pair, where each value is received by the page component. It should be a serializable object so that any props passed, could be serialized with JSON.stringify
.
revalidate
The revalidate
property is the amount in seconds after which a page re-generation can occur (defaults to false
or no revalidation).
Learn more about Incremental Static Regeneration.
The cache status of a page leveraging ISR can be determined by reading the value of the x-nextjs-cache
response header. The possible values are the following:
MISS
- the path is not in the cache (occurs at most once, on the first visit)STALE
- the path is in the cache but exceeded the revalidate time so it will be updated in the backgroundHIT
- the path is in the cache and has not exceeded the revalidate time
notFound
The notFound
boolean allows the page to return a 404
status and 404 Page. With notFound: true
, the page will return a 404
even if there was a successfully generated page before. This is meant to support use cases like user-generated content getting removed by its author. Note, notFound
follows the same revalidate
behavior described here.
Good to know:
notFound
is not needed forfallback: false
mode as only paths returned fromgetStaticPaths
will be pre-rendered.
redirect
The redirect
object allows redirecting to internal or external resources. It should match the shape of { destination: string, permanent: boolean }
.
In some rare cases, you might need to assign a custom status code for older HTTP
clients to properly redirect. In these cases, you can use the statusCode
property instead of the permanent
property, but not both. You can also set basePath: false
similar to redirects in next.config.js
.
If the redirects are known at build-time, they should be added in next.config.js
instead.
Reading files: Use process.cwd()
Files can be read directly from the filesystem in getStaticProps
.
In order to do so you have to get the full path to a file.
Since Next.js compiles your code into a separate directory you can't use __dirname
as the path it returns will be different from the Pages Router.
Instead you can use process.cwd()
which gives you the directory where Next.js is being executed.
Version History
Version | Changes |
---|---|
v13.4.0 | App Router is now stable with simplified data fetching |
v12.2.0 | On-Demand Incremental Static Regeneration is stable. |
v12.1.0 | On-Demand Incremental Static Regeneration added (beta). |
v10.0.0 | locale , locales , defaultLocale , and notFound options added. |
v10.0.0 | fallback: 'blocking' return option added. |
v9.5.0 | Stable Incremental Static Regeneration |
v9.3.0 | getStaticProps introduced. |