@@ -16,20 +16,16 @@ export async function getServerSideProps(context) {
...
@@ -16,20 +16,16 @@ export async function getServerSideProps(context) {
## When does getServerSideProps run
## When does getServerSideProps run
`getServerSideProps` only runs on server-side and never runs on the browser. If a page uses `getServerSideProps`, then:
`getServerSideProps` only runs on the server-side and never runs on the browser. If a page uses `getServerSideProps`, then:
- When you request this page directly, `getServerSideProps` runs at request time, and this page will be pre-rendered with the returned props
- When you request this page directly, `getServerSideProps` runs at request time, and this page will be pre-rendered with the returned props
- When you request this page on client-side page transitions through [`next/link`](/docs/api-reference/next/link.md) or [`next/router`](/docs/api-reference/next/router.md), Next.js sends an API request to the server, which runs `getServerSideProps`
- When you request this page on client-side page transitions through [`next/link`](/docs/api-reference/next/link.md) or [`next/router`](/docs/api-reference/next/router.md), Next.js sends an API request to the server, which runs `getServerSideProps`
It then returns `JSON` that contains the result of running `getServerSideProps`, that `JSON` will be used to render the page. All this work will be handled automatically by Next.js, so you don’t need to do anything extra as long as you have `getServerSideProps` defined.
It then returns `JSON` that contains the result of running `getServerSideProps`. That `JSON` will be used to render the page. All this work will be handled automatically by Next.js, so you don’t need to do anything extra as long as you have `getServerSideProps` defined.
You can use the [next-code-elimination tool](https://next-code-elimination.vercel.app/) to verify what Next.js eliminates from the client-side bundle.
Note that `getServerSideProps` can only be exported from a **page**. You can’t export it from non-page files. Also, you must export `getServerSideProps` as a standalone function — it will **not** work if you add `getServerSideProps` as a property of the page component.
`getServerSideProps` can only be exported from a **page**. You can’t export it from non-page files.
The [`getServerSideProps` API reference](/docs/api-reference/data-fetching/get-server-side-props.md) covers all parameters and props that can be used with `getServerSideProps`. Also, you can use the [next-code-elimination tool](https://next-code-elimination.vercel.app/) to verify what Next.js eliminates from the client-side bundle.
Note that you must export `getServerSideProps` as a standalone function — it will **not** work if you add `getServerSideProps` as a property of the page component.
The [`getServerSideProps` API reference](/docs/api-reference/data-fetching/get-server-side-props.md) covers all parameters and props that can be used with `getServerSideProps`.
@@ -35,7 +35,7 @@ You should use `getStaticPaths` if you’re statically pre-rendering pages that
...
@@ -35,7 +35,7 @@ You should use `getStaticPaths` if you’re statically pre-rendering pages that
## When does getStaticPaths run
## When does getStaticPaths run
`getStaticPaths` only runs at build time on server-side. If you're using [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md), `getStaticPaths` can also be run on-demand _in the background_, but still only on the server-side.
`getStaticPaths` only runs at build time on the server-side. If you're using [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md), `getStaticPaths` can also be run on-demand _in the background_, but still only on the server-side.
@@ -4,7 +4,30 @@ description: Fetch data and generate static pages with `getStaticProps`. Learn m
...
@@ -4,7 +4,30 @@ description: Fetch data and generate static pages with `getStaticProps`. Learn m
# getStaticProps
# getStaticProps
If you export a function called `getStaticProps` (Static Site Generation) from a page, Next.js will pre-render this page at build time using the props returned by `getStaticProps`.
If you export a function called `getStaticProps` (Static Site Generation) from a page, Next.js will pre-render this page at **build time** using the props returned by `getStaticProps`.
```jsx
```jsx
exportasyncfunctiongetStaticProps(context){
exportasyncfunctiongetStaticProps(context){
...
@@ -16,6 +39,10 @@ export async function getStaticProps(context) {
...
@@ -16,6 +39,10 @@ export async function getStaticProps(context) {
## When should I use getStaticProps?
## When should I use getStaticProps?
We recommend using Static Generation whenever possible because your page can be built once and served by CDN, which makes it much faster than having a server render the page on every request.
You can use Static Generation for many types of pages, including marketing pages, blog posts, and docs sites.
You should use `getStaticProps` if:
You should use `getStaticProps` if:
- The data required to render the page is available at build time ahead of a user’s request
- The data required to render the page is available at build time ahead of a user’s request
...
@@ -23,8 +50,6 @@ You should use `getStaticProps` if:
...
@@ -23,8 +50,6 @@ You should use `getStaticProps` if:
- The data can be publicly cached (not user-specific)
- 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
- 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 combined with [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md), `getStaticProps` will run in the background while the stale page is being revalidated, and the fresh page served to the browser.
Because `getStaticProps` runs at build time, it does **not** have access to the incoming request (such as query parameters or `HTTP` headers) as it generates static `HTML`. If you need access to the request for your page, consider using [Middleware](/docs/middleware.md) in addition to `getStaticProps`.
Because `getStaticProps` runs at build time, it does **not** have access to the incoming request (such as query parameters or `HTTP` headers) as it generates static `HTML`. If you need access to the request for your page, consider using [Middleware](/docs/middleware.md) in addition to `getStaticProps`.
## Using getStaticProps to fetch data from a CMS
## Using getStaticProps to fetch data from a CMS
...
@@ -43,7 +68,7 @@ function Blog({ posts }) {
...
@@ -43,7 +68,7 @@ function Blog({ posts }) {
)
)
}
}
// This function gets called at build time on server-side.
// This function gets called at build time on the server-side.
// It won't be called on client-side, so you can even do
// It won't be called on client-side, so you can even do
// direct database queries.
// direct database queries.
exportasyncfunctiongetStaticProps(){
exportasyncfunctiongetStaticProps(){
...
@@ -78,15 +103,15 @@ Alternatively, if you are **not** using API routes to fetch data, then the [`fet
...
@@ -78,15 +103,15 @@ Alternatively, if you are **not** using API routes to fetch data, then the [`fet
To verify what Next.js eliminates from the client-side bundle, you can use the [next-code-elimination tool](https://next-code-elimination.vercel.app/).
To verify what Next.js eliminates from the client-side bundle, you can use the [next-code-elimination tool](https://next-code-elimination.vercel.app/).
## Statically generates both HTML and JSON
## Generating an HTML and JSON file
When a page with `getStaticProps` is pre-rendered at build time, in addition to the page HTML file, Next.js generates a JSON file holding the result of running `getStaticProps`.
When a page with `getStaticProps` is pre-rendered at build time, in addition to the page HTML file, Next.js generates a JSON file holding the result of running `getStaticProps`.
This JSON file will be used in client-side routing through [`next/link`](/docs/api-reference/next/link.md) or [`next/router`](/docs/api-reference/next/router.md). When you navigate to a page that’s pre-rendered using `getStaticProps`, Next.js fetches this JSON file (pre-computed at build time) and uses it as the props for the page component. This means that client-side page transitions will **not** call `getStaticProps` as only the exported JSON is used.
This JSON file will be used in client-side routing through [`next/link`](/docs/api-reference/next/link.md) or [`next/router`](/docs/api-reference/next/router.md). When you navigate to a page that’s pre-rendered using `getStaticProps`, Next.js fetches this JSON file (pre-computed at build time) and uses it as the props for the page component. This means that client-side page transitions will **not** call `getStaticProps` as only the exported JSON is used.
When using Incremental Static Generation, `getStaticProps` will be executed in the background to generate the JSON needed for client-side navigation. You may see this in the form of multiple requests being made for the same page, however, this is intended and has no impact on end-user performance.
When using [Incremental Static Regeneration](/docs/basic-features/data-fetching/incremental-static-regeneration.md), `getStaticProps` will be executed in the background the JSON needed for client-side navigation. This is done while the stale page is being revalidated, and the fresh page served to the browser. You may see this in the form of multiple requests being made for the same page, however, this is intended and has no impact on end-user performance.
## Where can I use getStaticProps
## Where can I use getStaticProps?
`getStaticProps` can only be exported from a **page**. You **cannot** export it from non-page files.
`getStaticProps` can only be exported from a **page**. You **cannot** export it from non-page files.
@@ -4,25 +4,20 @@ description: 'Learn how to create or update static pages at runtime with Increme
...
@@ -4,25 +4,20 @@ description: 'Learn how to create or update static pages at runtime with Increme
# Incremental Static Regeneration
# Incremental Static Regeneration
<details>
Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
Incremental Static Regeneration works well for e-commerce, marketing pages, blog posts, ad-backed media, and more.
| -------- | ---------------- |
| `v9.5.0` | Base Path added. |
</details>
Consider an e-commerce store with 100,000 products. At a realistic 50ms to statically generate each product page, the build would take almost 2 hours without ISR. With ISR, we can choose from:
Next.js allows you to create or update static pages _after_ you’ve built your site. Incremental Static Regeneration (ISR) enables you to use static-generation on a per-page basis, **without needing to rebuild the entire site**. With ISR, you can retain the benefits of static while scaling to millions of pages.
-**Faster Builds** → Generate the most popular 1,000 products at build-time. Requests made to other products will be a cache miss and statically generate on-demand: 1-minute builds.
-**Higher Cache Hit Rate** → Generate 10,000 products at build-time, ensuring more products are cached ahead of a user's request: 8-minute builds.
The big advantage of ISR is having the flexibility to choose which pages are generated at build or on-demand. Choose from faster builds or more cached pages.
## Using ISR to fetch data from a blog
To use ISR add the `revalidate` prop to `getStaticProps`:
To use ISR add the `revalidate` prop to `getStaticProps`:
...
@@ -37,7 +32,7 @@ function Blog({ posts }) {
...
@@ -37,7 +32,7 @@ function Blog({ posts }) {
)
)
}
}
// This function gets called at build time on server-side.
// This function gets called at build time on the server-side.
// It may be called again, on a serverless function, if
// It may be called again, on a serverless function, if
// revalidation is enabled and a new request comes in
// revalidation is enabled and a new request comes in
exportasyncfunctiongetStaticProps(){
exportasyncfunctiongetStaticProps(){
...
@@ -55,7 +50,7 @@ export async function getStaticProps() {
...
@@ -55,7 +50,7 @@ export async function getStaticProps() {
}
}
}
}
// This function gets called at build time on server-side.
// This function gets called at build time on the server-side.
// It may be called again, on a serverless function, if
// It may be called again, on a serverless function, if
// the path has not been generated.
// the path has not been generated.
exportasyncfunctiongetStaticPaths(){
exportasyncfunctiongetStaticPaths(){
...
@@ -86,3 +81,18 @@ When a request is made to a page that was pre-rendered at build time, it will in
...
@@ -86,3 +81,18 @@ When a request is made to a page that was pre-rendered at build time, it will in
When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache.
When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache.
[Incremental Static Regeneration](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration) covers how to persist the cache globally and handle rollbacks.
[Incremental Static Regeneration](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration) covers how to persist the cache globally and handle rollbacks.
## Examples
-[**E-commerce Demo**](https://nextjs.org/commerce) – Next.js Commerce is an all-in-one starter kit for high-performance e-commerce sites.
-[**GitHub Reactions Demo**](https://reactions-demo.vercel.app/) – React to the original GitHub issue and watch ISR update the statically generated landing page.
-[Static Tweets Demo](https://static-tweet.vercel.app/) – This project deploys in 30 seconds, but can statically generate 500M tweets on-demand using ISR.
Data fetching in Next.js allows you to render your content in different ways, depending on your application's use case. These include pre-rendering with **Server-side Rendering** or **Static Generation**, and updating or creating content at runtime with **Incremental Static Regeneration**.
Data fetching in Next.js allows you to render your content in different ways, depending on your application's use case. These include pre-rendering with **Server-side Rendering** or **Static Generation**, updating or creating content at runtime with **Incremental Static Regeneration**, and traditional fetching on the client side.
@@ -6,7 +6,7 @@ description: Next.js pages are React Components exported in a file in the pages
...
@@ -6,7 +6,7 @@ description: Next.js pages are React Components exported in a file in the pages
> This document is for Next.js versions 9.3 and up. If you're using older versions of Next.js, refer to our [previous documentation](https://nextjs.org/docs/tag/v9.2.2/basic-features/pages).
> This document is for Next.js versions 9.3 and up. If you're using older versions of Next.js, refer to our [previous documentation](https://nextjs.org/docs/tag/v9.2.2/basic-features/pages).
In Next.js, a **page** is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory. Each page is associated with a route based on its file name.
In Next.js, a **page** is a [React Component](https://beta.reactjs.org/learn/your-first-component) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory. Each page is associated with a route based on its file name.
**Example**: If you create `pages/about.js` that exports a React component like below, it will be accessible at `/about`.
**Example**: If you create `pages/about.js` that exports a React component like below, it will be accessible at `/about`.
...
@@ -22,13 +22,13 @@ export default About
...
@@ -22,13 +22,13 @@ export default About
Next.js supports pages with dynamic routes. For example, if you create a file called `pages/posts/[id].js`, then it will be accessible at `posts/1`, `posts/2`, etc.
Next.js supports pages with dynamic routes. For example, if you create a file called `pages/posts/[id].js`, then it will be accessible at `posts/1`, `posts/2`, etc.
> To learn more about dynamic routing, check the [Dynamic Routing documentation](/docs/routing/dynamic-routes.md).
> To learn more about dynamic routing, check the [Dynamic Routes documentation](/docs/routing/dynamic-routes.md).
## Pre-rendering
## Pre-rendering
By default, Next.js **pre-renders** every page. This means that Next.js generates HTML for each page in advance, instead of having it all done by client-side JavaScript. Pre-rendering can result in better performance and SEO.
By default, Next.js **pre-renders** every page. This means that Next.js generates HTML for each page in advance, instead of having it all done by client-side JavaScript. Pre-rendering can result in better performance and SEO.
Each generated HTML is associated with minimal JavaScript code necessary for that page. When a page is loaded by the browser, its JavaScript code runs and makes the page fully interactive. (This process is called _hydration_.)
Each generated HTML is associated with minimal JavaScript code necessary for that page. When a page is loaded by the browser, its JavaScript code runs and makes the page fully interactive (This process is called _hydration_).
### Two forms of Pre-rendering
### Two forms of Pre-rendering
...
@@ -37,9 +37,9 @@ Next.js has two forms of pre-rendering: **Static Generation** and **Server-side
...
@@ -37,9 +37,9 @@ Next.js has two forms of pre-rendering: **Static Generation** and **Server-side
-[**Static Generation (Recommended)**](#static-generation-recommended): The HTML is generated at **build time** and will be reused on each request.
-[**Static Generation (Recommended)**](#static-generation-recommended): The HTML is generated at **build time** and will be reused on each request.
-[**Server-side Rendering**](#server-side-rendering): The HTML is generated on **each request**.
-[**Server-side Rendering**](#server-side-rendering): The HTML is generated on **each request**.
Importantly, Next.js lets you **choose** which pre-rendering form you'd like to use for each page. You can create a "hybrid" Next.js app by using Static Generation for most pages and using Server-side Rendering for others.
Next.js conveniently lets you **choose** which pre-rendering form you'd like to use for each page. You can create a "hybrid" Next.js app by using Static Generation for most pages and using Server-side Rendering for others.
We **recommend** using **Static Generation** over Server-side Rendering for performance reasons. Statically generated pages can be cached by CDN with no extra configuration to boost performance. However, in some cases, Server-side Rendering might be the only option.
We **recommend** using **Static Generation** over Server-side Rendering for performance reasons. Statically generated pages can be cached by a CDN with no extra configuration to boost performance. However, in some cases, Server-side Rendering might be the only option.
You can also use **Client-side Rendering** along with Static Generation or Server-side Rendering. That means some parts of a page can be rendered entirely by client side JavaScript. To learn more, take a look at the [Data Fetching](/docs/basic-features/data-fetching/client-side.md) documentation.
You can also use **Client-side Rendering** along with Static Generation or Server-side Rendering. That means some parts of a page can be rendered entirely by client side JavaScript. To learn more, take a look at the [Data Fetching](/docs/basic-features/data-fetching/client-side.md) documentation.
...
@@ -144,7 +144,7 @@ To learn more about how `getStaticProps` works, check out the [Data Fetching doc
...
@@ -144,7 +144,7 @@ To learn more about how `getStaticProps` works, check out the [Data Fetching doc
Next.js allows you to create pages with **dynamic routes**. For example, you can create a file called `pages/posts/[id].js` to show a single blog post based on `id`. This will allow you to show a blog post with `id: 1` when you access `posts/1`.
Next.js allows you to create pages with **dynamic routes**. For example, you can create a file called `pages/posts/[id].js` to show a single blog post based on `id`. This will allow you to show a blog post with `id: 1` when you access `posts/1`.
> To learn more about dynamic routing, check the [Dynamic Routing documentation](/docs/routing/dynamic-routes.md).
> To learn more about dynamic routing, check the [Dynamic Routes documentation](/docs/routing/dynamic-routes.md).
However, which `id` you want to pre-render at build time might depend on external data.
However, which `id` you want to pre-render at build time might depend on external data.
...
@@ -201,7 +201,7 @@ To learn more about how `getStaticPaths` works, check out the [Data Fetching doc
...
@@ -201,7 +201,7 @@ To learn more about how `getStaticPaths` works, check out the [Data Fetching doc
### When should I use Static Generation?
### When should I use Static Generation?
We recommend using **Static Generation** (with and without data) whenever possible because your page can be built once and served by CDN, which makes it much faster than having a server render the page on every request.
We recommend using **Static Generation** (with and without data) whenever possible because your page can be built once and served by a CDN, which makes it much faster than having a server render the page on every request.
You can use Static Generation for many types of pages, including:
You can use Static Generation for many types of pages, including:
...
@@ -249,7 +249,7 @@ export default Page
...
@@ -249,7 +249,7 @@ export default Page
As you can see, `getServerSideProps` is similar to `getStaticProps`, but the difference is that `getServerSideProps` is run on every request instead of on build time.
As you can see, `getServerSideProps` is similar to `getStaticProps`, but the difference is that `getServerSideProps` is run on every request instead of on build time.
To learn more about how `getServerSideProps` works, check out our [Data Fetching documentation](/docs/basic-features/data-fetching/get-server-side-props.md)
To learn more about how `getServerSideProps` works, check out our [Data Fetching documentation](/docs/basic-features/data-fetching/get-server-side-props.md).
## Summary
## Summary
...
@@ -286,6 +286,6 @@ We recommend you to read the following sections next:
...
@@ -286,6 +286,6 @@ We recommend you to read the following sections next: