Unverified Commit f6c60946 authored by Lee Robinson's avatar Lee Robinson Committed by GitHub

Clarify rewrites and other docs cleanup. (#24890)

Based on user feedback, this clarifies the difference between rewrites and redirects, as well as follows the new pattern for showing version history with a collapsible table. 
parent 4bc87e47
...@@ -4,7 +4,14 @@ description: Learn more about setting a base path in Next.js ...@@ -4,7 +4,14 @@ description: Learn more about setting a base path in Next.js
# Base Path # Base Path
> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out. <details>
<summary><b>Version History</b></summary>
| Version | Changes |
| -------- | ---------------- |
| `v9.5.0` | Base Path added. |
</details>
To deploy a Next.js application under a sub-path of a domain you can use the `basePath` config option. To deploy a Next.js application under a sub-path of a domain you can use the `basePath` config option.
......
...@@ -4,8 +4,6 @@ description: Add custom HTTP headers to your Next.js app. ...@@ -4,8 +4,6 @@ description: Add custom HTTP headers to your Next.js app.
# Headers # Headers
> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
<details open> <details open>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
...@@ -16,9 +14,10 @@ description: Add custom HTTP headers to your Next.js app. ...@@ -16,9 +14,10 @@ description: Add custom HTTP headers to your Next.js app.
<details> <details>
<summary><b>Version History</b></summary> <summary><b>Version History</b></summary>
| Version | Changes | | Version | Changes |
| --------- | ------------ | | --------- | -------------- |
| `v10.2.0` | `has` added. | | `v10.2.0` | `has` added. |
| `v9.5.0` | Headers added. |
</details> </details>
......
...@@ -4,8 +4,6 @@ description: Add redirects to your Next.js app. ...@@ -4,8 +4,6 @@ description: Add redirects to your Next.js app.
# Redirects # Redirects
> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
<details open> <details open>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
...@@ -16,9 +14,10 @@ description: Add redirects to your Next.js app. ...@@ -16,9 +14,10 @@ description: Add redirects to your Next.js app.
<details> <details>
<summary><b>Version History</b></summary> <summary><b>Version History</b></summary>
| Version | Changes | | Version | Changes |
| --------- | ------------ | | --------- | ---------------- |
| `v10.2.0` | `has` added. | | `v10.2.0` | `has` added. |
| `v9.5.0` | Redirects added. |
</details> </details>
......
...@@ -4,8 +4,6 @@ description: Add rewrites to your Next.js app. ...@@ -4,8 +4,6 @@ description: Add rewrites to your Next.js app.
# Rewrites # Rewrites
> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
<details open> <details open>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
...@@ -16,14 +14,17 @@ description: Add rewrites to your Next.js app. ...@@ -16,14 +14,17 @@ description: Add rewrites to your Next.js app.
<details> <details>
<summary><b>Version History</b></summary> <summary><b>Version History</b></summary>
| Version | Changes | | Version | Changes |
| --------- | ------------ | | --------- | --------------- |
| `v10.2.0` | `has` added. | | `v10.2.0` | `has` added. |
| `v9.5.0` | Rewrites added. |
</details> </details>
Rewrites allow you to map an incoming request path to a different destination path. Rewrites allow you to map an incoming request path to a different destination path.
Rewrites act as a URL proxy and mask the destination path, making it appear the user hasn't changed their location on the site. In contrast, [redirects](/docs/api-reference/next.config.js/redirects.md) will reroute to a new page a show the URL changes.
Rewrites are only available on the Node.js environment and do not affect client-side routing. Rewrites are only available on the Node.js environment and do not affect client-side routing.
To use rewrites you can use the `rewrites` key in `next.config.js`: To use rewrites you can use the `rewrites` key in `next.config.js`:
...@@ -326,7 +327,7 @@ module.exports = { ...@@ -326,7 +327,7 @@ module.exports = {
} }
``` ```
See additional information on incremental adoption [in the docs here](https://nextjs.org/docs/migrating/incremental-adoption). See additional information on incremental adoption [in the docs here](/docs/migrating/incremental-adoption.md).
### Rewrites with basePath support ### Rewrites with basePath support
......
...@@ -4,7 +4,14 @@ description: Configure Next.js pages to resolve with or without a trailing slash ...@@ -4,7 +4,14 @@ description: Configure Next.js pages to resolve with or without a trailing slash
# Trailing Slash # Trailing Slash
> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out. <details>
<summary><b>Version History</b></summary>
| Version | Changes |
| -------- | --------------------- |
| `v9.5.0` | Trailing Slash added. |
</details>
By default Next.js will redirect urls with trailing slashes to their counterpart without a trailing slash. For example `/about/` will redirect to `/about`. You can configure this behavior to act the opposite way, where urls without trailing slashes are redirected to their counterparts with trailing slashes. By default Next.js will redirect urls with trailing slashes to their counterpart without a trailing slash. For example `/about/` will redirect to `/about`. You can configure this behavior to act the opposite way, where urls without trailing slashes are redirected to their counterparts with trailing slashes.
......
...@@ -222,20 +222,27 @@ export default Blog ...@@ -222,20 +222,27 @@ export default Blog
### Incremental Static Regeneration ### Incremental Static Regeneration
> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5#stable-incremental-static-regeneration) and up. If you’re using older versions of Next.js, please upgrade before trying Incremental Static Regeneration.
<details open> <details open>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="https://reactions-demo.vercel.app/">Static Reactions Demo</a></li> <li><a href="https://nextjs.org/commerce">Next.js Commerce</a></li>
<li><a href="https://reactions-demo.vercel.app/">GitHub Reactions Demo</a></li>
<li><a href="https://static-tweet.vercel.app/">Static Tweet Demo</a></li>
</ul> </ul>
</details> </details>
With [`getStaticProps`](#getstaticprops-static-generation) you don't have to stop relying on dynamic content, as **static content can also be dynamic**. Incremental Static Regeneration allows you to update _existing_ pages by re-rendering them in the background as traffic comes in. <details>
<summary><b>Version History</b></summary>
| Version | Changes |
| -------- | ---------------- |
| `v9.5.0` | Base Path added. |
Inspired by [stale-while-revalidate](https://tools.ietf.org/html/rfc5861), background regeneration ensures traffic is served uninterruptedly, always from static storage, and the newly built page is pushed only after it's done generating. </details>
Consider our previous [`getStaticProps` example](#simple-example), but now with regeneration enabled: 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.
Consider our previous [`getStaticProps` example](#simple-example), but now with Incremental Static Regeneration enabled through the `revalidate` property:
```jsx ```jsx
function Blog({ posts }) { function Blog({ posts }) {
...@@ -261,25 +268,42 @@ export async function getStaticProps() { ...@@ -261,25 +268,42 @@ export async function getStaticProps() {
}, },
// Next.js will attempt to re-generate the page: // Next.js will attempt to re-generate the page:
// - When a request comes in // - When a request comes in
// - At most once every second // - At most once every 10 seconds
revalidate: 1, // In seconds revalidate: 10, // In seconds
} }
} }
// This function gets called at build time on server-side.
// It may be called again, on a serverless function, if
// the path has not been generated.
export async function getStaticPaths() {
const res = await fetch('https://.../posts')
const posts = await res.json()
// Get the paths we want to pre-render based on posts
const paths = posts.map((post) => ({
params: { id: post.id },
}))
// We'll pre-render only these paths at build time.
// { fallback: blocking } will server-render pages
// on-demand if the path doesn't exist.
return { paths, fallback: 'blocking' }
}
export default Blog export default Blog
``` ```
Now the list of blog posts will be revalidated once per second; if you add a new blog post it will be available almost immediately, without having to re-build your app or make a new deployment. When a request is made to a page that was pre-rendered at build time, it will initially show the cached page.
This works perfectly with [`fallback: true`](#fallback-true). Because now you can have a list of posts that's always up to date with the latest posts, and have a [blog post page](#fallback-pages) that generates blog posts on-demand, no matter how many posts you add or update.
#### Static content at scale - Any requests to the page after the initial request and before 10 seconds are also cached and instantaneous.
- After the 10-second window, the next request will still show the cached (stale) page
- Next.js triggers a regeneration of the page in the background.
- Once the page has been successfully generated, Next.js will invalidate the cache and show the updated product page. If the background regeneration fails, the old page remains unaltered.
Unlike traditional SSR, [Incremental Static Regeneration](#incremental-static-regeneration) ensures you retain the benefits of static: 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.
- No spikes in latency. Pages are served consistently fast To learn how to persist the cache globally and handle rollbacks, learn more about [Incremental Static Regeneration](https://vercel.com/docs/next.js/incremental-static-regeneration).
- Pages never go offline. If the background page re-generation fails, the old page remains unaltered
- Low database and backend load. Pages are re-computed at most once concurrently
### Reading files: Use `process.cwd()` ### Reading files: Use `process.cwd()`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment