chore: add docs on rewrites and redirects #767
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
the
type: chore
tiffafoo
reviewed
Nov 5, 2021
docs/redirects-rewrites.md
Outdated
| Version 4 of the Essential Next.js build plugin adds support for native Next.js [rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites) and [redirects](https://nextjs.org/docs/api-reference/next.config.js/redirects). These are defined in your `next.config.js` file and include support for some features that are not included in Netlify redirects and rewrites. | ||
|
|
||
| ## Using Netlify redirects and rewrites on a Next.js site | ||
| Every site on Netlify supports [redirects and rewrites](https://docs.netlify.com/routing/redirects/), which are defined in a `_redirects` file or `netlify.toml`, and sites that use this plugin are no exceptions. However there are some caveats to bear in mind when using them. The plugin generates several rewrites of its own, which are used to map paths from the site to different Netlify functions which handle SSR, preview mode and images, as well as assets in `/_next/static`. Any Netlify redirects or rewrites that you create take precedence over these rewrites, so you should avoid adding a root level rewrite, because that would override the rewrites required by the plugin. |
There was a problem hiding this comment.
[dust] Having an example here of what they should avoid vs what they should do might be helpful, but super clear changes 👌
tiffafoo
reviewed
Nov 5, 2021
tiffafoo
reviewed
Nov 5, 2021
tiffafoo
reviewed
Nov 5, 2021
| Netlify and Next.js redirects support different features and are evaluated at different points in the request lifecycle, so there are some considerations in deciding which one to use with your site. | ||
|
|
||
| ### When to use Netlify redirects or rewrites: | ||
| - Generally if your redirect can be handled with Netlify redirects, these are faster to evaluate and should be preferred. |
There was a problem hiding this comment.
[sand, not for this pr] I'm guessing we should have some metrics/blog posts showing why/how much Netlify is faster at some point.
tiffafoo
reviewed
Nov 5, 2021
tiffafoo
previously approved these changes
Nov 5, 2021
Release-as: 4.0.0-beta.6 Co-authored-by: Tiffany Le-Nguyen <tiffany@netlify.com>
tiffafoo
approved these changes
Nov 8, 2021
rstavchansky
reviewed
Nov 8, 2021
| Version 4 of the Essential Next.js build plugin adds support for native Next.js [rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites) and [redirects](https://nextjs.org/docs/api-reference/next.config.js/redirects). These are defined in your `next.config.js` file and include support for some features that are not included in Netlify redirects and rewrites. | ||
|
|
||
| ## Using Netlify redirects and rewrites on a Next.js site | ||
| Every site on Netlify supports [redirects and rewrites](https://docs.netlify.com/routing/redirects/), which are defined in a `_redirects` file or `netlify.toml`, and sites that use this plugin are no exceptions. However there are some caveats to bear in mind when using them. The plugin generates several rewrites of its own, which are used to map paths from the site to different Netlify functions which handle SSR, preview mode and images, as well as assets in `/_next/static`. Any Netlify redirects or rewrites that you create [take precedence over these rewrites](#Redirect-and-rewrite-precedence), so you should avoid adding a root level rewrite, because that would override the rewrites required by the plugin. |
There was a problem hiding this comment.
I'm late to the party on this one after being out for a few days, but an example of what you mean by a root level rewrite could be useful. I may be off base, but something like this?
/* /index.html 200
If you make this addition, this sentence could benefit from one more Netlify mention to be crystal clear:
Any Netlify redirects or rewrites that you create take precedence over these rewrites, so you should avoid adding a root level Netlify rewrite, because that would override the rewrites required by the plugin.
|
|
||
| If you are using a monorepo you will need to change `publish` to point to the full path to the built `.next` directory, which may be in a subdirectory. If you have changed your `distDir` then it will need to match that. | ||
|
|
||
| If you are using Nx, then you will need to point `publish` to the folder inside `dist`, e.g. `dist/apps/myapp/.next`. | ||
|
|
||
| If you currently use redirects or rewrites on your site, see [the Rewrites and Redirects guide](https://github.com/netlify/netlify-plugin-nextjs/blob/main/docs/rewrites-and-redirects.md) for information on changes to how they are handled in this version. |
There was a problem hiding this comment.
This link is causing a 404 error. It should point here: https://github.com/netlify/netlify-plugin-nextjs/blob/main/docs/redirects-rewrites.md
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds a page to the plugin docs that explains some of the subtleties of how redirects and rewrites now work in the plugin.
Fixes #756
Rendered version