Next.js Build Plugin

This build plugin is a utility for supporting Next.js on Netlify. To enable server-side rendering and other framework-specific features in your Next.js application on Netlify, you will need to install this plugin for your app.

Table of Contents

• Installation and Configuration
• Custom Netlify Functions
• Publish Directory
• Custom Netlify Redirects
• Caveats
• Credits
• Showcase

Installation and Configuration

There are two ways to install the plugin in your Next.js on Netlify site: with the Netlify UI or with file-based installation.

UI-based Installation

You can install this plugin using this direct in-app installation link or from your team's Plugins directory in the Netlify UI.

Read more about UI-based plugin installation in our docs.

File-based Installation

1. Create a netlify.toml in the root of your project. Your file should include the plugins section below:

   [build]
     command   = "npm run build"
   
   [[plugins]]
     package = "@netlify/plugin-nextjs"

2. From your project's base directory, use npm, yarn, or any other Node.js package manager to add this plugin to devDependencies in package.json.

   npm install -D @netlify/plugin-nextjs
   

   or

   yarn add -D @netlify/plugin-nextjs
   

Read more about file-based plugin installation in our docs.

Custom Netlify Functions

This plugin creates one Netlify Function for each Next.js page that requires one. To use custom Netlify Functions in addition to what the plugin generates, add a path to your functions folder in netlify.toml:

[build]
  command   = "npm run build"
  functions = "my_functions_dir"

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

Read more about Netlify Functions in our docs.

Publish Directory

Similarly, you can customize your publish directory in your netlify.toml file:

[build]
  command   = "npm run build"
  functions = "my_functions_dir"
  publish   = "my_publish_dir"

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

Read more about Netlify's build settings in our docs.

Custom Netlify Redirects

You can define custom redirects in a _redirects file. The precedence of these rules are:

• _redirects
• next-on-netlify redirects

Read more about Netlify redirects in our docs.

Caveats

Versions

You can check our package.json for supported Next and Node versions. Our support of Next 10 is currently experimental.

CLI

This plugin is currently not stable for use with the Netlify CLI. Support for the plugin is in development.

Fallbacks for Pages with getStaticPaths

Fallback pages behave differently with this plugin than they do with Next.js. On Next.js, when navigating to a path that is not defined in getStaticPaths, it first displays the fallback page. Next.js then generates the HTML in the background and caches it for future requests.

With this plugin, when navigating to a path that is not defined in getStaticPaths, it server-side renders the page and sends it directly to the user. The user never sees the fallback page. The page is not cached for future requests.

For more on this, see: Issue #7

Credits

This package is maintained by Lindsay Levine and Cassidy Williams. It extends the project next-on-netlify, authored originally by Finn Woelm.

Showcase

The following sites are built with next-on-netlify:

opinionatedreact.com (via Twitter)

missionbit.org (#18)