Docs content for OpenNext runtime

opennextjs · Oct 22, 2024 · 8dc5596 · 8dc5596
1 parent 59fc954
commit 8dc5596
Show file tree

Hide file tree

Showing 3 changed files with 174 additions and 3 deletions.
diff --git 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
@@ -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
+   <html>
+     <head></head>
+     <body>
+       <form name="feedback" data-netlify="true" hidden>
+         <input type="hidden" name="form-name" value="feedback" />
+         <input name="name" type="text" />
+         <input name="email" type="text" />
+         <input name="message" type="text" />
+       </form>
+     </body>
+   </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 (
+       <form name="feedback" onSubmit={handleFormSubmit}>
+         <input type="hidden" name="form-name" value="feedback" />
+         <input name="name" type="text" placeholder="Name" required />
+         <input name="email" type="text" placeholder="Email (optional)" />
+         <button type="submit">Submit</button>
+       </form>
+     );
+   }
+   ```
+
+## 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
@@ -1,6 +1,97 @@
 import { SITE } from "../../config";
 import { Callout } from "nextra/components";
 
-## Netlify
+# Next.js on Netlify
 
-TODO
+<a href="https://runtime-e2e-report.netlify.app/" target="_blank">
+  <img
+    src="https://runtime-e2e-report.netlify.app/badge"
+    width="185"
+    height="25"
+    style={{ borderRadius: 0, marginTop: "1rem" }}
+    alt="Netlify Next.js runtime v5 test status"
+  />
+</a>
+
+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.