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 has specific configuration considerations and leverages On-demand Builders.

  • AMP support. The next/amp component enables the creation of Accelerated Mobile Pages (AMP) to achieve faster load times on mobile devices.

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

In addition to the Next.js-specific items above, the following Netlify features provide a full-fledged site development and monitoring experience.

  • Redirects, rewrites, & headers. You can use Netlify's built-in routing capabilities to configure redirects and rewrites or to update headers.

  • Analytics. To monitor trends in site activity for a Next.js project on Netlify, you can leverage Netlify Analytics.

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.

Use built-in Next.js bundling instead of Netlify bundling

Enabling JavaScript bundling for asset optimization on Netlify 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.

# 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 effectively creates a Netlify Function for each Next.js page that requires one. The plugin automatically stores the resulting serverless functions in your site’s functions directory. You can add custom Netlify Functions to the same directory, and they’ll be automatically detected and deployed.

For more detailed information about using the Essential Next.js plugin with your site, check out the plugin documentation. Topics include monorepos, image handling, custom serverless functions, redirects, and more.

Uninstall the plugin

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.

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

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.

# Edit next.config.js

If you’re using the Essential Next.js build plugin for an app with server-side rendering and your project has a preexisting next.config.js file, configure the project’s target to serverless mode. This enables the build plugin to create a standalone serverless function for every page that requires one.

module.exports = {
  target: "serverless"
}

Redirects and rewrites using next.config.js aren’t currently supported for Next.js sites on Netlify. If you have these specified in a next.config.js file for your project, check out our redirects and rewrites docs to learn how to set them up in a _redirects or netlify.toml file instead.

# More resources