chore: add more docs (#1130)

* chore: add more docs

* chore: apply suggestions from code review

Co-authored-by: Kyle Rollins <[email protected]>

Co-authored-by: Kyle Rollins <[email protected]>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

Author: 3 people

README.md

@@ -31,6 +31,12 @@ npm install -D @netlify/plugin-nextjs
 package = "@netlify/plugin-nextjs"
 ```
 
+## Deploying
+
+If you build on Netlify, this plugin will work with no additional configuration. However if you are building and
+deploying locally using the Netlify CLI, you must deploy using `netlify deploy --build`. Running the
+build and deploy commands separately will not work, because the plugin will not generate the required configuration.
+
 ## Migrating from an older version of the plugin
 
 You can manually upgrade from the previous version of the plugin by running the following command:
@@ -58,7 +64,8 @@ it.
 
 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/redirects-rewrites.md)
-for information on changes to how they are handled in this version.
+for information on changes to how they are handled in this version. In particular, note that `_redirects` and `_headers`
+files must be placed in `public`, not in the root of the site.
 
 If you want to use Next 12's beta Middleware feature, this will mostly work as expected but please
 [read the docs on some caveats and workarounds](https://github.com/netlify/netlify-plugin-nextjs/blob/main/docs/middleware.md)
@@ -85,6 +92,12 @@ you can remove it. Alternatively you can
 support. See [`demos/next-export`](https://github.com/netlify/netlify-plugin-nextjs/tree/main/demos/next-export) for an
 example.
 
+## Asset optimization
+
+Netlify [asset optimization](https://docs.netlify.com/site-deploys/post-processing/) should not be used with Next.js
+sites. Assets are already optimized by Next.js at build time, and doing further optimization can break your site. Ensure
+that it is not enabled at **Site settings > Build & deploy > Post processing > Asset optimization**.
+
 ## Generated functions
 
 This plugin works by generating three Netlify functions that handle requests that haven't been pre-rendered. These are

docs/redirects-rewrites.md

@@ -24,3 +24,7 @@ Netlify and Next.js redirects support different features and are evaluated at di
 ### 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.
+
+### Using `_rewrites` and `_headers` files
+
+If you are using `_rewrites` or `_headers` files rather than a `netlify.toml` file, bear in mind that these files must be in the published directory of your site, not the root of the repo. To do this, put them in `public` and they will be moved into `.next` at build time. Do not put them directly into `.next`, because it is emptied at build time. Any `_rewrites` or `_headers` files in the root of the repo will not be found when deployed.