Netlify Docs
Ask Netlify

Contact

Frameworks /Framework support /Next.js /

Next.js 13.5+ on Netlify

Next.js is a React-based open source framework that allows you to build server-side rendered and statically generated web applications with ease.

Next.js 13.5 and later

The information on this page applies to Next.js version 13.5 or later, running on Netlify’s Next.js Runtime v5.

This runtime version is rolled out to all sites meeting the prerequisites, with the exception of:

For earlier Next.js versions, go to the Runtime v4 page.

# Next.js Runtime v5

Netlify Next.js runtime v5 test status

The role of our Next.js runtime is to automatically configure your site to enable 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.), making that functionality work 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.

# 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 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.

# Prerequisites

# Breaking changes

  • Netlify Forms. If you’re currently using Netlify Forms, you would typically need to make some changes to your code. See Netlify Forms Compatibility.

  • Advanced API routes. If your site uses advanced API routes (background or scheduled functions implemented as Next.js API routes), you will need to convert these to regular Netlify Functions. See notes and code examples.

After completing the necessary changes to your code, you can manually opt-in to Runtime v5 from the Site Overview screen of your site.

# Limitations

Currently, Next.js Runtime v5 has the following limitations:

  • SSR pages set to the edge runtime will run in your functions 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

Netlify Forms use automatic detection of form tag attributes (for 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 anymore, because any page can be revalidated at runtime. Instead, relevant pages are pre-rendered at build time, and then stored in Next.js’ own 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 cannot be the form’s target page as well. Any Netlify Forms-related attributes set in these pages have no effect.

To use Netlify Forms with Next.js 13.5 and above:

  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>
    <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>
  1. Lastly, the form submission should be JavaScript-based, making an AJAX POST request to the static HTML file you’ve create above. 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:

'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 & error handling should come here
  };

  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>
  );
}

For a more complete example which includes handling of submission states (success, error or pending), visit the live demo or explore the code for the form component and the required static file.

Note: to prevent silent failures of form detection or submission (either by users implementing Netlify Forms now or just moving to the v5 runtime), we now trigger an intentional build failure when suspecting your code is incompatible:

@netlify/plugin-nextjs@5 requires migration steps to support Netlify Forms. Refer to https://ntl.fyi/next-runtime-forms-migration for migration example.

These are the conditions triggering this failure:

  • The runtime has found usage of netlify or data-netlify form attributes in your React code (which now have no effect!).
  • Additionally, no static HTML file was found in your public directory having such form attributes (thus marking that you’ve implemented the approach laid out above).

Disabling the build failure if necessary

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 via an environment variable.

Add a new environment variable NETLIFY_NEXT_VERIFY_FORMS to your site, and give it the value false.

# Troubleshooting

If you opt in through the Netlify UI without the correct Next.js or Node version, the following message will appear in your deploy log:

To upgrade this plugin, please uninstall and re-install it from the Netlify plugins directory

This deploy log message is incorrect. Instead of uninstalling and reinstalling the plugin, you need to change your Next.js version and Node version to match the prerequisites.

# Pin an older version of Next.js Runtime to your site

If you find that you need to return to Next.js Runtime v4, you can pin that version to your site.

This will prevent your site from automatically upgrading to Runtime v5 when that version becomes the default.

  1. Install the v4 version of the @netlify/plugin-nextjs package:

      npm i @netlify/plugin-nextjs@4

  2. In your netlify.toml, add:

      [[plugins]]
  package = "@netlify/plugin-nextjs"

# Suggested configuration values

When you link a 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 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 for Next.js.

# 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 with a value of --shamefully-hoist. This appends a --shamefully-hoist argument to the pnpm install command that Netlify runs.

  • Enable public hoisting by adding an .npmrc file in the root of your project with this content:

    public-hoist-pattern[]=*

Learn more about using pnpm on Netlify.

# More resources

←