Next.js on Netlify

Next.js is a React-based open source framework that provides a hybrid static / server-side rendered model for enterprise-grade sites and applications.

# Key features

These Next.js features provide important benefits for sites and apps, including those built and deployed with Netlify.

  • Page routing. Next.js boasts a file system-based routing structure. Organizing files and subdirectories within a pages directory automatically results in corresponding routes. The next/router component allows access to the router object inside components of an application, and the next/link component enables client-side transitions between routes. Other routing highlights include dynamic routes, catch all routes, shallow routing that changes a URL without fetching data again, and client-side routing with optimized prefetching.

  • Automatic API endpoints. For simpler API management, any file added to the pages/api directory is treated as an API endpoint with a corresponding API route.

  • Preview mode. Netlify supports rendering a draft page from any data-fetching solution instead of building a statically-generated page to preview. This preview mode functionality eliminates waiting for a build to run before previewing new content.

  • Hybrid or static. Depending on project needs, you can either leverage a hybrid approach for generating content or export a completely static site. The hybrid approach allows a choice between server-side rendering or static generation on a per-page basis. Meanwhile, the next export command generates a completely static site for deployment.

  • Image optimization. The next/image component allows you to automatically optimize images for your site on-demand, as they’re requested by users. On Netlify, next/image uses ipx and On-demand Builders.

  • Incremental Static Regeneration (ISR). ISR on Netlify works with On-demand Builders to revalidate pages as needed without rebuilding your entire site. This enables faster builds, especially for very large projects.

  • Internationalization. Netlify supports Next.js internationalized routing functionality for locale-specific options.

The Next.js framework also includes developer-friendly features such as hot code reloading, automatic code splitting, TypeScript support, a variety of styling options, and built-in support for environment variables. All of these are available when you build with Netlify.

# Netlify integration

When you link a repository for a new site, Netlify tries to detect the framework your project is using. If your project uses Next.js, Netlify automatically installs the Essential Next.js build plugin and provides suggested configuration values. For existing sites already linked to Netlify, you can choose to install the plugin yourself.

# Essential Next.js build plugin

Essential Next.js configures your site on Netlify to enable key Next.js functionality. It generates three serverless functions that handle SSR pages, ISR, and images.

For more detailed information about using the Essential Next.js plugin with your site, check out the plugin documentation. Topics include what's new, redirects, rewrites, middleware, and troubleshooting large functions.

You can remove the plugin if needed. If you’re building a Next.js project that’s exported to a static application, you don’t need the extra features enabled in the Build Plugin for your project to deploy with Netlify.

# Redirects and rewrites

The Essential Next.js build plugin supports native Next.js rewrites and redirects. These are defined in your next.config.js file and support some features that are not included in Netlify redirects and rewrites.

We recommend using Netlify redirects when possible because they are faster to evaluate. Rewrites are a little different. Generally with this plugin, you should use Next.js rewrites instead of Netlify rewrites.

Avoid root-level rewrite

Do not add a rewrite from the site root (such as from = "/") in netlify.toml or _redirects. Your root-level rewrite would take precedence over the Essential Next.js build plugin's own rewrites and break routing on your site.

For a full description of when to use Netlify and Next.js redirects and rewrites, check out the plugin documentation.

# Limitations

  • During deployment, a function is packaged into a ZIP file, which AWS limits to 50 MB in size. Some functions generated by The Essential Next.js build plugin may exceed that limit and throw an error. This can happen for a few reasons. The plugin documentation has more information for troubleshooting.

  • Don't enable JavaScript bundling for asset optimization on Netlify. This can result in site build issues for a Next.js project with server-side rendering. Note that Next.js automatically bundles your project without this setting enabled.

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

serverless target deprecated

The serverless and experimental-serverless-trace targets are deprecated in Next 12, and all builds with the Essential Next.js plugin will now use the default server target. If you previously set the target in your next.config.js, you should remove it.

# More resources