From 59fc9549ada0ac105637c9e1e5619888492e48bd Mon Sep 17 00:00:00 2001 From: Sean C Davis Date: Tue, 22 Oct 2024 09:29:51 -0400 Subject: [PATCH 1/4] Blank space for Netlify --- pages/_meta.json | 3 ++- pages/index.mdx | 3 ++- pages/netlify/_meta.json | 3 +++ pages/netlify/index.mdx | 6 ++++++ 4 files changed, 13 insertions(+), 2 deletions(-) create mode 100644 pages/netlify/_meta.json create mode 100644 pages/netlify/index.mdx diff --git a/pages/_meta.json b/pages/_meta.json index 6375005..43f637a 100644 --- a/pages/_meta.json +++ b/pages/_meta.json @@ -1,5 +1,6 @@ { "index": "Overview", "aws": "AWS", - "cloudflare": "Cloudflare" + "cloudflare": "Cloudflare", + "netlify": "Netlify" } diff --git a/pages/index.mdx b/pages/index.mdx index 6bf21c2..b52b10c 100644 --- a/pages/index.mdx +++ b/pages/index.mdx @@ -1,4 +1,4 @@ -import { SITE } from '../config'; +import { SITE } from "../config"; # OpenNext @@ -18,6 +18,7 @@ OpenNext is currently backed by: 1. [SST](https://sst.dev) community, maintains the [AWS](aws) adapter 2. [Cloudflare](https://developers.cloudflare.com/) team, maintains the [Cloudflare](cloudflare) adapter +3. [Netlify](https://www.netlify.com/) team, maintains the [Netlify](netlify) adapter If you'd like to join the effort, connect with us on [Discord](https://discord.gg/opennextjs). diff --git a/pages/netlify/_meta.json b/pages/netlify/_meta.json new file mode 100644 index 0000000..ca0a2a6 --- /dev/null +++ b/pages/netlify/_meta.json @@ -0,0 +1,3 @@ +{ + "index": "Overview" +} diff --git a/pages/netlify/index.mdx b/pages/netlify/index.mdx new file mode 100644 index 0000000..8c08a37 --- /dev/null +++ b/pages/netlify/index.mdx @@ -0,0 +1,6 @@ +import { SITE } from "../../config"; +import { Callout } from "nextra/components"; + +## Netlify + +TODO From 8dc5596b5dbd745d85d6de7c3f2d02f10197bf9b Mon Sep 17 00:00:00 2001 From: Sean C Davis Date: Tue, 22 Oct 2024 14:34:19 -0400 Subject: [PATCH 2/4] Docs content for OpenNext runtime --- pages/netlify/_meta.json | 3 +- pages/netlify/forms.mdx | 79 +++++++++++++++++++++++++++++++++ pages/netlify/index.mdx | 95 +++++++++++++++++++++++++++++++++++++++- 3 files changed, 174 insertions(+), 3 deletions(-) create mode 100644 pages/netlify/forms.mdx diff --git a/pages/netlify/_meta.json b/pages/netlify/_meta.json index ca0a2a6..abb54ab 100644 --- a/pages/netlify/_meta.json +++ b/pages/netlify/_meta.json @@ -1,3 +1,4 @@ { - "index": "Overview" + "index": "Overview", + "forms": "Netlify Forms" } diff --git a/pages/netlify/forms.mdx b/pages/netlify/forms.mdx new file mode 100644 index 0000000..55b6f18 --- /dev/null +++ b/pages/netlify/forms.mdx @@ -0,0 +1,79 @@ +# Using Netlify Forms with Next.js + +Netlify Forms use [automatic detection of form tag attributes](https://docs.netlify.com/get-started/#set-up-netlify-forms) (example: `data-netlify`) at deploy time by scanning any static HTML files present or generated during the build. + +As a security and anti-spam measure, only form and field names that Netlify detects at deployment are recognized by Netlify. When submitting a form, the form target URL must also be a static file. + +However, modern Next.js versions do not generate fully-static HTML pages because any page can be revalidated at runtime. Instead, relevant pages are pre-rendered at build time, and then stored in Next.js’s cache for serving. This means that your Next.js pages, including any form tags and attributes, are not written to static HTML files at deployment, and therefore cannot be the form’s target page. Attributes related to Netlify Forms set in these pages have no effect. + +## Workaround for Netlify Forms + +Here's one way to work around this limitation: + +1. Create a new HTML file in the `public` directory of your site. This file would be used for deploy-time form detection only. It can have any name, for example `public/__forms.html`. +2. In that file, add form tags for all your Netlify forms and fields. In the below example, note that only the bare minimum is needed, as users would not see this HTML page at all. + + ```html + + + + + + + ``` + +3. In your dynamic page or form component, handle the submission by serving a `POST` request to the static HTML file you’ve created above (using the example above: `/__forms`). + +4. Once the request is completed, you should show a success notification or navigate to another page. Here’s a simplified example of the form component: + + ```jsx + "use client"; + + export function FeedbackForm() { + const handleFormSubmit = async (event) => { + event.preventDefault(); + const formData = new FormData(event.target); + await fetch("/__forms.html", { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: new URLSearchParams(formData).toString(), + }); + // Success and error handling ... + }; + + return ( +
+ + + + +
+ ); + } + ``` + +## Live demo + +For a more complete example which includes handling of submission states (success, error or pending), visit the [live demo](https://nextjs-platform-starter.netlify.app/classics) or explore the code for the [form component](https://github.com/netlify-templates/next-platform-starter/blob/main/components/feedback-form.jsx) and the [required static file](https://github.com/netlify-templates/next-platform-starter/blob/main/public/__forms.html). + +## Prevent silent failures + +To prevent silent failures of form detection or submission, we now trigger an intentional build failure when suspecting your code is incompatible: + +```txt +@netlify/plugin-nextjs@5 requires migration steps to support Netlify Forms. Refer to https://ntl.fyi/next-runtime-forms-migration for migration example. +``` + +This failure is triggered when both of the following conditions are met: + +- The runtime has found usage of `netlify` or `data-netlify` form attributes in your React code (which have no effect). +- No static HTML file was found in your `public` directory having form attributes (thus marking that you’ve implemented the approach laid out above). + +### Skip the check + +If you believe that a check failure is incorrect or would like to defer handling the issue to a later time, you can skip this check by adding a `NETLIFY_NEXT_VERIFY_FORMS` environment variable to your site, with the value `false`. diff --git a/pages/netlify/index.mdx b/pages/netlify/index.mdx index 8c08a37..87b630f 100644 --- a/pages/netlify/index.mdx +++ b/pages/netlify/index.mdx @@ -1,6 +1,97 @@ import { SITE } from "../../config"; import { Callout } from "nextra/components"; -## Netlify +# Next.js on Netlify -TODO + + Netlify Next.js runtime v5 test status + + +Netlify's Next.js runtime automatically configures Netlify sites with key functionality, including cache control, on-demand revalidation, and image optimization. + +The runtime provisions serverless and edge functions as appropriate to handle your site’s server-side functionality (such as SSR, ISR and PPR pages, API endpoints, Server Actions, Edge Middleware, etc.), ensuring that functionality works out-of-the-box. + +We automatically verify compatibility with the latest stable version of Next.js, using the comprehensive end-to-end tests of the framework itself. To access up-to-date test results, use the badge above. + +## Get started + +The easiest way to get started is to deploy our Next.js platform starter template to your Netlify account. Use the button below to get started. + +[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/netlify-templates/next-platform-starter) + +### Prerequisites + +- Next.js version 13.5 and later (up to the latest stable version) +- [Node 18.x or later](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript) +- The latest version of [Netlify CLI](https://docs.netlify.com/cli/get-started/) + +## Key features + +- **App Router:** Netlify fully supports the Next.js App Router, which supports more powerful nested layouts and React’s latest features, such as Server Components and Streaming. + +- **Automatic fine-grained caching:** Next.js Runtime v5 uses fine-grained caching on Netlify to support the Next.js Full Route Cache and Data Cache. This means that static page responses are automatically cached at the edge and can be revalidated by path or by tag. + +- **On-demand and time-based revalidation:** Both the App Router and Pages Router support on-demand and time-based revalidation, allowing you to revalidate and regenerate content at any time after a deploy. + +- **Image optimization:** The `next/image` component uses [Netlify Image CDN](https://docs.netlify.com/image-cdn/overview/) by default to ensure your images are optimized and served in the most efficient format. + +Note that while we also generally support experimental features (for example, Partial Prerendering) from their early stages, such features are not considered stable yet at the framework level. + +## Automatic runtime detection + +Netlify automatically detects that you're using Next.js and provisions your site with the most up-to-date runtime. + +### Pin a specific runtime version + +To pin the Netlify Next.js runtime to a specific version, read [the Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). + +### Suggested configuration values + +When you [link a repository](https://docs.netlify.com/welcome/add-new-site/#import-from-an-existing-repository) for a Next.js project, Netlify provides a suggested build command and publish directory: `next build` and `.next`. + +If you’re using the CLI to run [Netlify Dev](https://docs.netlify.com/cli/local-development/) for a local development environment, Netlify suggests a dev command and port: `next` and `3000`. + +You can override suggested values or set them in a configuration file instead, but suggested values from automatic framework detection may help simplify the process of setting up a Next.js site on Netlify. + +For manual configuration, check out the [typical build settings](https://docs.netlify.com/frameworks/#next-js) for Next.js. + +## Limitations + +Currently, Netlify's Next.js runtime has the following limitations: + +- **SSR pages set to the `edge` runtime will run in your [functions region](https://docs.netlify.com/functions/optional-configuration/#region).** If edge-level performance is critical, we advise that you use static pages with edge functions instead. They are rendered at the origin, but are then cached at the edge and can be revalidated on demand. + +- **Rewrites in your Next.js configuration can’t point to static files in the `public` directory.** If you create `beforeFiles` rewrites in your `next.config.js`, they can’t point to static files in your site’s `public` directory. You can use middleware rewrites as an alternative. + +- **Netlify Forms compatibility:** Using Netlify Forms with the current runtime [requires a workaround](/netlify/forms). + +### pnpm support + +If you’re planning to use pnpm with Next.js to manage dependencies, you must do one of the following: + +- Set a `PNPM_FLAGS` [environment variable](https://docs.netlify.com/environment-variables/get-started/#create-environment-variables) with a value of `--shamefully-hoist`. This appends a `--shamefully-hoist` argument to the `pnpm install` command that Netlify runs. +- [Enable public hoisting](https://pnpm.io/npmrc#public-hoist-pattern) by adding an `.npmrc` file in the root of your project with this content: + + ```bash + public-hoist-pattern[]=* + ``` + +Learn more about using [pnpm on Netlify](https://docs.netlify.com/configure-builds/manage-dependencies/#pnpm). + +## Troubleshooting + +The OpenNext docs are specifically about using Netlify's Next.js runtime v5.8 and later. For older versions of the runtime, refer to the [Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). + +If you need help with any version of the runtime, visit [our support page](https://www.netlify.com/support) for various methods of finding answers and getting help. + +### More resources + +- [Typical Next.js build settings](https://docs.netlify.com/frameworks/#next-js) +- [Next.js framework documentation](https://nextjs.org/docs/getting-started) +- [Connect JavaScript client](https://docs.netlify.com/connect/access-data/#use-the-connect-client) - the recommended library for querying Connect data layer APIs in Next.js cached SSR sites. From 20052a88e1376c29b1a1bfe7a1b04f113d5642e3 Mon Sep 17 00:00:00 2001 From: Sean C Davis Date: Tue, 22 Oct 2024 20:47:29 -0400 Subject: [PATCH 3/4] "runtime" -> "adapter" --- pages/netlify/forms.mdx | 2 +- pages/netlify/index.mdx | 28 ++++++++++++++-------------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/pages/netlify/forms.mdx b/pages/netlify/forms.mdx index 55b6f18..fb2b9b6 100644 --- a/pages/netlify/forms.mdx +++ b/pages/netlify/forms.mdx @@ -71,7 +71,7 @@ To prevent silent failures of form detection or submission, we now trigger an in This failure is triggered when both of the following conditions are met: -- The runtime has found usage of `netlify` or `data-netlify` form attributes in your React code (which have no effect). +- The adapter has found usage of `netlify` or `data-netlify` form attributes in your React code (which have no effect). - No static HTML file was found in your `public` directory having form attributes (thus marking that you’ve implemented the approach laid out above). ### Skip the check diff --git a/pages/netlify/index.mdx b/pages/netlify/index.mdx index 87b630f..466c7d3 100644 --- a/pages/netlify/index.mdx +++ b/pages/netlify/index.mdx @@ -9,13 +9,13 @@ import { Callout } from "nextra/components"; width="185" height="25" style={{ borderRadius: 0, marginTop: "1rem" }} - alt="Netlify Next.js runtime v5 test status" + alt="Netlify Next.js adapter v5 test status" /> -Netlify's Next.js runtime automatically configures Netlify sites with key functionality, including cache control, on-demand revalidation, and image optimization. +Netlify's Next.js adapter automatically configures Netlify sites with key functionality, including cache control, on-demand revalidation, and image optimization. -The runtime provisions serverless and edge functions as appropriate to handle your site’s server-side functionality (such as SSR, ISR and PPR pages, API endpoints, Server Actions, Edge Middleware, etc.), ensuring that functionality works out-of-the-box. +The adapter provisions serverless and edge functions as appropriate to handle your site’s server-side functionality (such as SSR, ISR and PPR pages, API endpoints, Server Actions, Edge Middleware, etc.), ensuring that functionality works out-of-the-box. We automatically verify compatibility with the latest stable version of Next.js, using the comprehensive end-to-end tests of the framework itself. To access up-to-date test results, use the badge above. @@ -35,21 +35,21 @@ The easiest way to get started is to deploy our Next.js platform starter templat - **App Router:** Netlify fully supports the Next.js App Router, which supports more powerful nested layouts and React’s latest features, such as Server Components and Streaming. -- **Automatic fine-grained caching:** Next.js Runtime v5 uses fine-grained caching on Netlify to support the Next.js Full Route Cache and Data Cache. This means that static page responses are automatically cached at the edge and can be revalidated by path or by tag. +- **Automatic fine-grained caching:** thehe adapter uses fine-grained caching on Netlify to support the Next.js Full Route Cache and Data Cache. This means that static page responses are automatically cached at the edge and can be revalidated by path or by tag. -- **On-demand and time-based revalidation:** Both the App Router and Pages Router support on-demand and time-based revalidation, allowing you to revalidate and regenerate content at any time after a deploy. +- **On-demand and time-based revalidation:** both the App Router and Pages Router support on-demand and time-based revalidation, allowing you to revalidate and regenerate content at any time after a deploy. -- **Image optimization:** The `next/image` component uses [Netlify Image CDN](https://docs.netlify.com/image-cdn/overview/) by default to ensure your images are optimized and served in the most efficient format. +- **Image optimization:** the `next/image` component uses [Netlify Image CDN](https://docs.netlify.com/image-cdn/overview/) by default to ensure your images are optimized and served in the most efficient format. Note that while we also generally support experimental features (for example, Partial Prerendering) from their early stages, such features are not considered stable yet at the framework level. -## Automatic runtime detection +## Automatic framework detection -Netlify automatically detects that you're using Next.js and provisions your site with the most up-to-date runtime. +Netlify automatically detects that you're using Next.js and provisions your site with the most up-to-date adapter. -### Pin a specific runtime version +### Pin a specific adapter version -To pin the Netlify Next.js runtime to a specific version, read [the Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). +To pin the Netlify Next.js adapter to a specific version, read [the Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). ### Suggested configuration values @@ -63,13 +63,13 @@ For manual configuration, check out the [typical build settings](https://docs.ne ## Limitations -Currently, Netlify's Next.js runtime has the following limitations: +Currently, Netlify's Next.js adapter has the following limitations: - **SSR pages set to the `edge` runtime will run in your [functions region](https://docs.netlify.com/functions/optional-configuration/#region).** If edge-level performance is critical, we advise that you use static pages with edge functions instead. They are rendered at the origin, but are then cached at the edge and can be revalidated on demand. - **Rewrites in your Next.js configuration can’t point to static files in the `public` directory.** If you create `beforeFiles` rewrites in your `next.config.js`, they can’t point to static files in your site’s `public` directory. You can use middleware rewrites as an alternative. -- **Netlify Forms compatibility:** Using Netlify Forms with the current runtime [requires a workaround](/netlify/forms). +- **Netlify Forms compatibility:** Using Netlify Forms with the current adapter [requires a workaround](/netlify/forms). ### pnpm support @@ -86,9 +86,9 @@ Learn more about using [pnpm on Netlify](https://docs.netlify.com/configure-buil ## Troubleshooting -The OpenNext docs are specifically about using Netlify's Next.js runtime v5.8 and later. For older versions of the runtime, refer to the [Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). +The OpenNext docs are specifically about using Netlify's Next.js adapter v5.9 and later. For older versions of the adapter, refer to the [Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). -If you need help with any version of the runtime, visit [our support page](https://www.netlify.com/support) for various methods of finding answers and getting help. +If you need help with any version of the adapter, visit [our support page](https://www.netlify.com/support) for various methods of finding answers and getting help. ### More resources From 416cb09d32e3a1dec65b746697070e190e22c7f3 Mon Sep 17 00:00:00 2001 From: Philippe Serhal Date: Wed, 23 Oct 2024 14:52:35 -0400 Subject: [PATCH 4/4] fix: don't mention new package name yet --- pages/netlify/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/netlify/index.mdx b/pages/netlify/index.mdx index 466c7d3..cd301f5 100644 --- a/pages/netlify/index.mdx +++ b/pages/netlify/index.mdx @@ -86,7 +86,7 @@ Learn more about using [pnpm on Netlify](https://docs.netlify.com/configure-buil ## Troubleshooting -The OpenNext docs are specifically about using Netlify's Next.js adapter v5.9 and later. For older versions of the adapter, refer to the [Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). +The OpenNext docs are specifically about using Netlify's Next.js adapter v5 and later. For older versions of the adapter, refer to the [Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/). If you need help with any version of the adapter, visit [our support page](https://www.netlify.com/support) for various methods of finding answers and getting help.