Skip to content

Commit 8dc5596

Browse files
seancdavisseancdavis
committed
Docs content for OpenNext runtime
1 parent 59fc954 commit 8dc5596

File tree

3 files changed

+174
-3
lines changed

3 files changed

+174
-3
lines changed

‎pages/netlify/_meta.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
{
2-
"index": "Overview"
2+
"index": "Overview",
3+
"forms": "Netlify Forms"
34
}

‎pages/netlify/forms.mdx

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Using Netlify Forms with Next.js
2+
3+
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.
4+
5+
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.
6+
7+
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.
8+
9+
## Workaround for Netlify Forms
10+
11+
Here's one way to work around this limitation:
12+
13+
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`.
14+
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.
15+
16+
```html
17+
<html>
18+
<head></head>
19+
<body>
20+
<form name="feedback" data-netlify="true" hidden>
21+
<input type="hidden" name="form-name" value="feedback" />
22+
<input name="name" type="text" />
23+
<input name="email" type="text" />
24+
<input name="message" type="text" />
25+
</form>
26+
</body>
27+
</html>
28+
```
29+
30+
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`).
31+
32+
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:
33+
34+
```jsx
35+
"use client";
36+
37+
export function FeedbackForm() {
38+
const handleFormSubmit = async (event) => {
39+
event.preventDefault();
40+
const formData = new FormData(event.target);
41+
await fetch("/__forms.html", {
42+
method: "POST",
43+
headers: { "Content-Type": "application/x-www-form-urlencoded" },
44+
body: new URLSearchParams(formData).toString(),
45+
});
46+
// Success and error handling ...
47+
};
48+
49+
return (
50+
<form name="feedback" onSubmit={handleFormSubmit}>
51+
<input type="hidden" name="form-name" value="feedback" />
52+
<input name="name" type="text" placeholder="Name" required />
53+
<input name="email" type="text" placeholder="Email (optional)" />
54+
<button type="submit">Submit</button>
55+
</form>
56+
);
57+
}
58+
```
59+
60+
## Live demo
61+
62+
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).
63+
64+
## Prevent silent failures
65+
66+
To prevent silent failures of form detection or submission, we now trigger an intentional build failure when suspecting your code is incompatible:
67+
68+
```txt
69+
@netlify/plugin-nextjs@5 requires migration steps to support Netlify Forms. Refer to https://ntl.fyi/next-runtime-forms-migration for migration example.
70+
```
71+
72+
This failure is triggered when both of the following conditions are met:
73+
74+
- The runtime has found usage of `netlify` or `data-netlify` form attributes in your React code (which have no effect).
75+
- No static HTML file was found in your `public` directory having form attributes (thus marking that you’ve implemented the approach laid out above).
76+
77+
### Skip the check
78+
79+
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`.

‎pages/netlify/index.mdx

Lines changed: 93 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,97 @@
11
import { SITE } from "../../config";
22
import { Callout } from "nextra/components";
33

4-
## Netlify
4+
# Next.js on Netlify
55

6-
TODO
6+
<a href="https://runtime-e2e-report.netlify.app/" target="_blank">
7+
<img
8+
src="https://runtime-e2e-report.netlify.app/badge"
9+
width="185"
10+
height="25"
11+
style={{ borderRadius: 0, marginTop: "1rem" }}
12+
alt="Netlify Next.js runtime v5 test status"
13+
/>
14+
</a>
15+
16+
Netlify's Next.js runtime automatically configures Netlify sites with key functionality, including cache control, on-demand revalidation, and image optimization.
17+
18+
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.
19+
20+
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.
21+
22+
## Get started
23+
24+
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.
25+
26+
[![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)
27+
28+
### Prerequisites
29+
30+
- Next.js version 13.5 and later (up to the latest stable version)
31+
- [Node 18.x or later](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript)
32+
- The latest version of [Netlify CLI](https://docs.netlify.com/cli/get-started/)
33+
34+
## Key features
35+
36+
- **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.
37+
38+
- **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.
39+
40+
- **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.
41+
42+
- **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.
43+
44+
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.
45+
46+
## Automatic runtime detection
47+
48+
Netlify automatically detects that you're using Next.js and provisions your site with the most up-to-date runtime.
49+
50+
### Pin a specific runtime version
51+
52+
To pin the Netlify Next.js runtime to a specific version, read [the Netlify docs](https://docs.netlify.com/frameworks/next-js/overview/).
53+
54+
### Suggested configuration values
55+
56+
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`.
57+
58+
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`.
59+
60+
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.
61+
62+
For manual configuration, check out the [typical build settings](https://docs.netlify.com/frameworks/#next-js) for Next.js.
63+
64+
## Limitations
65+
66+
Currently, Netlify's Next.js runtime has the following limitations:
67+
68+
- **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.
69+
70+
- **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.
71+
72+
- **Netlify Forms compatibility:** Using Netlify Forms with the current runtime [requires a workaround](/netlify/forms).
73+
74+
### pnpm support
75+
76+
If you’re planning to use pnpm with Next.js to manage dependencies, you must do one of the following:
77+
78+
- 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.
79+
- [Enable public hoisting](https://pnpm.io/npmrc#public-hoist-pattern) by adding an `.npmrc` file in the root of your project with this content:
80+
81+
```bash
82+
public-hoist-pattern[]=*
83+
```
84+
85+
Learn more about using [pnpm on Netlify](https://docs.netlify.com/configure-builds/manage-dependencies/#pnpm).
86+
87+
## Troubleshooting
88+
89+
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/).
90+
91+
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.
92+
93+
### More resources
94+
95+
- [Typical Next.js build settings](https://docs.netlify.com/frameworks/#next-js)
96+
- [Next.js framework documentation](https://nextjs.org/docs/getting-started)
97+
- [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.

0 commit comments

Comments
 (0)