From c3a28f86fe2f06389671465b730da6196550a757 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Fri, 27 Jan 2023 14:31:32 -0800 Subject: [PATCH] replace repo links with netlify docs links and remove repo doc files --- README.md | 6 +-- docs/isr.md | 81 -------------------------------------- docs/large-functions.md | 26 ------------ docs/middleware.md | 54 ------------------------- docs/redirects-rewrites.md | 58 --------------------------- docs/release-notes/v4.md | 10 ++--- 6 files changed, 8 insertions(+), 227 deletions(-) delete mode 100644 docs/isr.md delete mode 100644 docs/large-functions.md delete mode 100644 docs/middleware.md delete mode 100644 docs/redirects-rewrites.md diff --git a/README.md b/README.md index 10774b845d..52284fb088 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ Next.js Middleware works out of the box on Netlify. By default, middleware runs support for running Middleware at the origin, set the environment variable `NEXT_DISABLE_NETLIFY_EDGE` to `true`. Be aware that this will result in slower performance, as all pages that match middleware must use SSR. -For more details on Next.js Middleware with Netlify, see the [middleware docs](https://github.com/netlify/next-runtime/blob/main/docs/middleware.md). +For more details on Next.js Middleware with Netlify, see the [middleware docs](https://docs.netlify.com/integrations/frameworks/next-js/middleware/). ### Limitations @@ -74,7 +74,7 @@ If you are using Nx, then you will need to point `publish` to the folder inside ## Incremental Static Regeneration (ISR) The Next.js Runtime fully supports ISR on Netlify. For more details see -[the ISR docs](https://github.com/netlify/next-runtime/blob/main/docs/isr.md). +[the ISR docs](https://docs.netlify.com/integrations/frameworks/next-js/incremental-static-regeneration/). Note that Netlify has a minimum TTL of 60 seconds for revalidation. @@ -144,7 +144,7 @@ Runtime will now use the default `server` target. If you previously set the targ remove it. If you currently use redirects or rewrites on your site, see -[the Rewrites and Redirects guide](https://github.com/netlify/next-runtime/blob/main/docs/redirects-rewrites.md) for +[the Rewrites and Redirects guide](https://docs.netlify.com/integrations/frameworks/next-js/redirects-and-rewrites/) 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. diff --git a/docs/isr.md b/docs/isr.md deleted file mode 100644 index a25da61347..0000000000 --- a/docs/isr.md +++ /dev/null @@ -1,81 +0,0 @@ -## Incremental Static Regeneration (ISR) - -[Incremental static regeneration](https://vercel.com/docs/concepts/next.js/incremental-static-regeneration) is a feature -of Next.js that allows pages to be updated after a site has been built and deployed. It is now fully supported in -Netlify by the Next Runtime, meaning large sites can update pages without needing to rebuild the entire site. Unlike -server-side rendered pages, the page is not rebuilt for each user, so they load quickly, but unlike statically-generated -pages they can be periodically updated with new content without a new deploy. - -### Using ISR on Netlify - -ISR on Netlify is implemented with [On Demand Builders](https://docs.netlify.com/configure-builds/on-demand-builders/), -using the TTL feature. You can enable ISR for a page by returning a value for `revalidate` from the `getStaticProps` -function. This value is the number of seconds for which the content will be considered fresh. If a request arrives for a -page after the `revalidate` period has elapsed, the page will be regenerated. ISR uses a "stale while revalidate" -strategy, meaning that the visitor still receives the stale content, but it is regenerated in the background ready for -the next request. The generated page is persisted globally, so is available to all visitors wherever they are in the -world. It is also cached in the global Netlify CDN so responses are fast. - -The minimum value for `revalidate` is 60 seconds, and any value less than that will be rounded-up to 60 seconds. After a -request is made for stale content, the page will be regenerated in the background and immediately persisted globally, -but it can take up to 60 seconds before the new content is then updated in all CDN nodes if they already had a cached -copy. - -If the static regeneration relies on local files in your repository they need to be bundled with the handler functions. -This can be done by modifying your -[file based configuration](https://docs.netlify.com/configure-builds/file-based-configuration). An entry to the -`included_files` option needs to be added under the `functions` option. You should be careful to not include unnecessary -files, particularly large files such as images or videos, because there is a 50MB size limit for each handler function. -See [Functions Configuration Docs](https://docs.netlify.com/configure-builds/file-based-configuration/#functions) for -more info. Update your `netlify.toml` file to include the following (assuming local content is located in the /content -directory): - -```toml -[functions] -included_files = ["content/**"] -``` - -If you only need the content for DSG pages, then you can target only that function like this: - -```toml -[functions.__dsg] -included_files = ["content/**"] -``` - -or, for SSR pages: - -```toml -[functions.__ssr] -included_files = ["content/**"] -``` - -If a new deploy is made, all persisted pages and CDN cached pages will be invalidated so that conflicts are avoided. If -this did not happen, a stale HTML page might make a request for an asset that no longer exists in the new deploy. By -invalidating all persisted pages, you can be confident that this will never happen and that deploys remain atomic. - -### On-demand ISR - -On-Demand ISR (where a path is manually revalidated) is not currently supported on Netlify. -[Please let us know](https://github.com/netlify/next-runtime/discussions/1228) if this feature would be useful to you, -and if so how you would plan to use it. - -### Alternatives to ISR - -ISR is best for situations where there are regular updates to content throughout the day, particularly you don't have -control over when it happens. It is less ideal in situations such as a CMS with incremental updates where you can have -the CMS trigger a deploy when a page is added or edited. This offers the best performance and avoids unnecesary -rebuilds. - -#### Static site generation - -For high-traffic pages you can use -[static generation](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) without -`revalidate`, which deploys static files directly to the CDN for maximum performance. - -#### Distributed persistent rendering - -For less commonly-accessed content you can use return `fallback: "blocking"` from -[`getStaticPaths`](https://nextjs.org/docs/basic-features/data-fetching#getstaticpaths-static-generation) and defer -builds until the first request. This also uses On Demand Builders, but persists the built page until the next deploy. -This is great for long-tail content and archives that don't change often but are not accessed often enough to justify -statically-generating them at build time. diff --git a/docs/large-functions.md b/docs/large-functions.md deleted file mode 100644 index 2b37459e57..0000000000 --- a/docs/large-functions.md +++ /dev/null @@ -1,26 +0,0 @@ -## Troubleshooting large functions - -You may see an error about generated functions being too large. This is because when deploying your site it is packaged -into a zipfile, which is limited by AWS to 50MB in size. There are two possible causes for this, each with its own -solution. The list of largest files shown in the build logs will help you see what the cause is. - -- **Large dependencies** This is the most common cause of the problem. Some node modules are very large, mostly those - that include native modules. Examples include `electron` and `chromium`. The function bundler is usually able to find - out which modules are actually used by your code, but sometimes it will incorrectly include unneeded modules. If this - is the case, you can either remove the module from your dependencies if you installed it yourself, or exclude it - manually by adding something like this to your `netlify.toml`, changing the value according to the problematic module. - The `!` at the beginning of the module path indicates that it should be excluded: - - ```toml - [functions] - included_files = ["!node_modules/a-large-module/**/*"] - ``` - - If you do need large modules at runtime (e.g. if you are running Puppeteer in a Next API route), consider changing to - a Netlify function which will have less overhead than the equivalent Next.js function. - -- **Large numbers of pre-rendered pages** If you have a very large number of pre-rendered pages, these can take up a lot - of space in the function. There are two approaches to fixing this. One is to consider deferring the building of the - pages. If you return `fallback: "blocking"` from `getStaticPaths` the rendering will be deferred until the first user - requests the page. This is a good choice for low-traffic pages. It reduces build and deploy time, and can make your - bundle a lot smaller. diff --git a/docs/middleware.md b/docs/middleware.md deleted file mode 100644 index e4e7ff9f6e..0000000000 --- a/docs/middleware.md +++ /dev/null @@ -1,54 +0,0 @@ -# Using Next.js 12 middleware on Netlify - -Next.js 12 introduces a new feature called [Middleware](https://nextjs.org/docs/middleware), in which functions run before -a request has finished processing. Middleware can be used to modify the request or replace the response. For example, it -can change headers, rewrite the request path, or return a different response entirely. - -Next.js Middleware can run either in an edge function (highly recommended for version 12.2+ as ISR will not work -otherwise) or at the origin. On Netlify, Middleware runs at the origin as part of the normal Next.js server. - -## How to deploy Next.js 12 middleware - -Next.js 12 Middleware works out of the box with Netlify, and most functions will work unchanged. By default, middleware runs using Netlify Edge Functions. For legacy support for running Middleware at the origin, set the environment variable `NEXT_DISABLE_NETLIFY_EDGE` to `true`. Be aware that this will result in slower performance, as all pages that match middleware must use SSR. See [the middleware docs](https://nextjs.org/docs/middleware) for details of how to create Next.js middleware. There are however a few workarounds that are currently required for some features during the beta period: - -### `geo` - -When running at the origin, Next.js does not populate the `request.geo` object as part of the -[NextRequest](https://nextjs.org/docs/api-reference/next/server#nextrequest). Fortunately there is a one line fix to get -the visitor's country: - -```typescript -export async function middleware(req: NextRequest) { - // Add this line - req.geo.country = req.headers.get('x-country') - - // The rest of your middleware goes here -} -``` - -### `ip` - -Next.js also does not populate the `req.ip` value when running at the origin. There is another one line fix for this: - -```typescript -export async function middleware(req: NextRequest) { - // Add this line - req.ip = req.headers.get('x-nf-client-connection-ip') - - // The rest of your middleware goes here -} -``` - -## Caveats when middleware is run at the origin - -When the middleware runs at the origin, it is run _after_ Netlify rewrites and redirects. If a static file is served by -the Netlify CDN then the middleware is never run, as middleware only runs when a page is served by Next.js. This means -that any pages that match middleware routes are served from the origin rather than the CDN. - -There is a bug in Next.js `<=12.0.3` that causes a proxy loop if you try to rewrite to a URL with a host other than -localhost. This bug is fixed in version `12.0.4`, so if you are using middleware you should upgrade to that version or -later. - -If you have an issue with Next.js middleware on Netlify while it is beta, particularly if the issue cannot be reproduced -when running locally, then please add a comment to -[the Next Runtime beta discussion](https://ntl.fyi/next-beta-feedback). diff --git a/docs/redirects-rewrites.md b/docs/redirects-rewrites.md deleted file mode 100644 index ee7de3ac72..0000000000 --- a/docs/redirects-rewrites.md +++ /dev/null @@ -1,58 +0,0 @@ -# Redirects and rewrites - -Version 4 of the Next Runtime 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 the Next Runtime are no exceptions. However there are some -caveats to bear in mind when using them. The Next Runtime 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 Netlify -rewrite, because that would override the rewrites generated by and required by the runtime. - -## 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 rewrites, not redirects. -- If you need Next.js-specific features such as regex path or header matching, you must use Next.js rewrites. - -### Using `_redirects` and `_headers` files - -If you are using `_redirects` 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 -`_redirects` or `_headers` files in the root of the repo will not be found when deployed. diff --git a/docs/release-notes/v4.md b/docs/release-notes/v4.md index 6b8346245a..8a2aeca019 100644 --- a/docs/release-notes/v4.md +++ b/docs/release-notes/v4.md @@ -6,10 +6,10 @@ stability. ## What's new - Full support for - [incremental static regeneration (ISR)](https://github.com/netlify/next-runtime/blob/main/docs/isr.md). + [incremental static regeneration (ISR)](https://docs.netlify.com/integrations/frameworks/next-js/incremental-static-regeneration/). - Full support for - [Next.js rewrites, redirects and headers](https://github.com/netlify/next-runtime/blob/main/docs/redirects-rewrites.md). -- Beta support for [Next.js 12 Middleware](https://github.com/netlify/next-runtime/blob/main/docs/middleware.md) + [Next.js rewrites, redirects and headers](https://docs.netlify.com/integrations/frameworks/next-js/redirects-and-rewrites/). +- Beta support for [Next.js 12 Middleware](https://docs.netlify.com/integrations/frameworks/next-js/middleware/) - Faster builds and deploys. Instead of generating one function per route, there are just three functions per site and a much smaller list of rewrites. - Full support for Netlify's new [persistent On-Demand Builders](https://ntl.fyi/odb). Return `fallback: "blocking"` @@ -41,10 +41,10 @@ If you previously set these values, they're no longer needed and can be removed: - `external_node_modules` in `netlify.toml` If you currently use redirects or rewrites on your site, see -[the Rewrites and Redirects guide](https://github.com/netlify/next-runtime/blob/main/docs/redirects-rewrites.md) for +[the Rewrites and Redirects guide](https://docs.netlify.com/integrations/frameworks/next-js/redirects-and-rewrites/) for information on changes to how they are handled in this version. If you currently have `_redirects` or `_headers` files in the root of your site, these will need to be moved into "public". If you want to use Next.js 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/next-runtime/blob/main/docs/middleware.md) +[read the docs on some caveats and workarounds](https://docs.netlify.com/integrations/frameworks/next-js/middleware/) that are currently needed.