chore: add docs on rewrites and redirects

README.md

@@ -34,14 +34,16 @@ publish = ".next"
 package = "@netlify/plugin-nextjs"
 ```
 
-If you previously set `target: "serverless"` or a custom `distDir` in your `next.config.js`, or set `node_bundler` or `external_node_modules` in your `netlify.toml` these are no longer needed and can be removed. 
+If you previously set a custom `distDir` in your `next.config.js`, or set `node_bundler` or `external_node_modules` in your `netlify.toml` these are no longer needed and can be removed. 
 
-The `serverless` and `experimental-serverless-trace` targets are deprecated in Next 12, and all builds with this plugin will now use the default `server` target.
+The `serverless` and `experimental-serverless-trace` targets are deprecated in Next 12, and all builds with this plugin will now use the default `server` target. If you previously set the target in your `next.config.js`, you should remove it.
 
 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.
+
 ## Beta feedback
 
 Please share any thoughts, feedback or questions about the beta [in our discussion](https://github.com/netlify/netlify-plugin-nextjs/discussions/706).

docs/redirects-rewrites.md

@@ -0,0 +1,26 @@
+# Redirects and rewrites
+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.
+
+## Redirect and rewrite precedence
+Rewrites and redirects are applied in the following order:
+
+1. Redirects and rewrites in the `_redirects` file. These are read in order until a match is found, and then processing stops.
+2. Redirects and rewrites in the `netlify.toml` file. None of these are read if one previous rules has already matched.
+3. At this point, if the request targets a static file then it will be returned, without the Next.js redirects or rewrites being evaluated.
+4. Any request that does not target a static file will then be passed to Next.js, and then will evaluate redirects and rewrites (which are defined in the `next.config.js` file).
+
+## General principles
+
+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.
+- [Identity](https://docs.netlify.com/visitor-access/identity/), [proxying](https://docs.netlify.com/routing/redirects/rewrites-proxies/) and [country-based redirects](https://docs.netlify.com/routing/redirects/) are Netlify-specific features and must use Netlify redirects.
+- If you need redirects or rewrites to be applied before loading static files, you must use Netlify redirects and rewrites.
+
+### When to use Next.js redirects or rewrites:
+- If you are using a _rewrite_ that points to a dynamic Next.js page, you must use Next.js rewrites. Next.js has no way of knowing what the rewritten page is when using Netlify rewrites, so the wrong page is likely to be rendered. This only applies to redirects, not rewrites.
+- If you need Next.js-specific features such as regex path or header matching, you must use Next.js rewrites.