README.md

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
• CLI Usage
• 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"
     publish = "out"
   
   [[plugins]]
     package = "@netlify/plugin-nextjs"

You can also add context-specific properties and environment variables to your netlify.toml. Read more about deploy contexts in our docs. For example:

```toml
[context.production.environment]
NEXT_SERVERLESS = "true"
NODE_ENV = "production"
```

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.

CLI Usage

If you'd like to build and deploy your project using the Netlify CLI, we recommend this workflow to manage git tracking plugin-generated files:

1. Make sure all your project's files are committed before running a build with the CLI
2. Run any number of builds and deploys freely (i.e. netlify build, netlify deploy --build, netlify deploy --prod)
3. Run git stash --include-unstaged to easily ignore plugin-generated files

Plugin-generated files will output into either (a) the default functions and publish directories (netlify/functions and ., respectively) or (b) whichever custom functions and publish directories you configure. See below for custom directory configuration. It's important to note that, in both cases (a) and (b), the CLI may mix your project's source code and plugin-generated files; this is why we recommend committing all project source files before running CLI builds.

Debugging CLI builds:

• If you're seeing a {FILE_NAME} already exists error running a CLI build, this may be because your node_modules got purged between builds or because of lingering unstashed files from outdated builds. To resolve, you need to manually remove any plugin-generated files from your project directory.

We're looking to improve the CLI experience to avoid this manual cleanup and git management! Feel free to open an issue to report feedback on the CLI experience.

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.

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)