Next.js on Netlify

Netlify’s Next.js adapter automatically configures Netlify sites to enable key functionality, including Server-Side Rendering (SSR), Incremental Static Regeneration (ISR), and image optimization. Our adapter is maintained in the open as part of the OpenNext initiative.

The adapter provisions Netlify Functions to handle your site’s server-side functionality (such as SSR, ISR and PPR pages, API endpoints, Server Actions, etc.), and Netlify Edge Functions for Edge Middleware, 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, plus our own tests suite.

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

# 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: the adapter uses our fine-grained caching primitives 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.

A note on experimental framework features (e.g., Partial Prerendering): generally, we support these as soon as possible, so you can evaluate these on Netlify early. However, such features are not considered stable yet at the framework level, and our support for these features cannot be guaranteed to work in full.

# Next.js support on Netlify

The following tables show you a comprehensive mapping of critical Next.js features and how Netlify supports them.

# Limitations

Open issues are documented in the end-to-end test report page.

• Edge Runtime Location: SSR pages using the edge runtime run in your functions region rather than true edge locations
• Rewrite Limitations: Rewrites in Next.js configuration can’t point to static files in the public directory.
• Middleware Execution Order: Headers and redirects are evaluated after middleware, differing from stand-alone Next.js behavior.
• Forms Integration: Netlify Forms requires a specific workaround when used with Next.js applications. Learn more.

# Upgrading from earlier versions

We actively maintain the v5 adapter to support all Next.js versions starting from version 13.5 and above. When you trigger a new build, the latest compatible adapter version is used.

# Upgrade steps

1. Review the breaking changes.
2. Upgrade Next.js to 13.5 or later, and Node.js to 18 or later.
3. Remove any references to @netlify/plugin-nextjs in your package.json and netlify.toml files, if there are any.
4. Trigger a new deploy, and checks its logs to verify that the v5 adapter is used, with no error.

# Breaking changes

Before upgrading to v5, review the following breaking changes:

• Netlify Forms: If you’re currently using Netlify Forms, you will likely need to make some changes to your code. Review the Netlify Forms compatibility page on OpenNext for details.

• 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. Review the notes and code examples.

# Reverting to an older adapter version

If you find that you need to return to a specific version of the Next.js adapter or runtime, you can pin that version to your site.

We recommend that you don’t pin the adapter version. We actively maintain the v5 adapter to support all Next.js versions starting from version 13.5 and, if you don’t pin the version, we will automatically update the adapter to the latest version on each site build for you.

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

     npm i @netlify/plugin-nextjs@1.2.3
    

2. In your netlify.toml, add:

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

# More resources

• OpenNext adapter docs
• Next.js framework documentation
• Connect JavaScript client - the recommended library for querying Connect data layer APIs in server-rendered Next.js sites.
• Posts about Next.js in our blog