netlify-plugin-nextjs v0.1.0
Next.js Build Plugin
This build plugin is a utility for enabling server-side rendering in Next.js on Netlify. It wraps your application in a tiny compatibility layer, so that pages can use Netlify Functions to be server-side rendered.
TL;DR: You can enable SSR in your Next.js applications with 3 simple steps, listed here!
Table of Contents
Installation and Configuration
npm install netlify-plugin-nextjs
Create a
netlify.toml
in the root of your poject:
[build]
command = "npm run build"
functions = "out_functions"
publish = "out_publish"
[[plugins]]
package = "netlify-plugin-nextjs"
Optional Extras
Preview Locally
I recommend you still use next dev
to build and preview your application locally.
But if you want to emulate the Netlify deployment on your computer, you can also run next-on-netlify
locally and then use netlify-cli
to preview the result.
First, install the latest version of netlify-cli
(you can also look at package.json to see the version that next-on-netlify has been tested against):
npm install -g netlify-cli
Then, add the following [dev]
block to your netlify.toml
:
# netlify.toml
# [build]
# ...
[dev]
functions = "out_functions"
publish = "out_publish"
# We manually set the framework to static, otherwise Netlify automatically
# detects Next.js and redirects do not work.
# Read more: https://github.com/netlify/cli/blob/master/docs/netlify-dev.md#project-detection
framework = "#static"
Lastly, add the following lines to your .gitignore
:
# .gitignore
# Files generated by next-on-netlify command
/out_publish/
/out_functions/
Now you're all set.
From now on, whenever you want to preview your application locally, just run:
npm run build
: This will runnext build
to build your Next.js app andnext-on-netlify
to prepare your Next.js app for compatibility with Netlifynetlify dev
: This will emulate Netlify on your computer and let you preview your app onhttp://localhost:8888
.
Custom Netlify Redirects
You can define custom redirects in a _redirects
and/or in your netlify.toml
file.
The precedence of these rules are:
_redirects
next-on-netlify
redirectsnetlify.toml
Read more about Netlify redirects here.
Custom Netlify Functions
next-on-netlify
creates one Netlify Function for each of your
SSR pages and API endpoints. It is currently not possible to create custom Netlify Functions. Let me know if you have a need for this feature and we can add it.
Caveats
Fallbacks for Pages with getStaticPaths
Fallback pages behave differently with next-on-netlify
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 next-on-netlify
, 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, Finn Woelm, and Cassidy Williams.
š£ Shoutout to @mottox2 (a pioneer of hosting Next.js on Netlify) and @danielcondemarin (author of serverless-next.js for AWS). The two were big inspirations for this package.
š Big "thank you" to the following people for their contributions, support, and beta testing:
Showcase
The following sites are built with next-on-netlify
:
opinionatedreact.com (via Twitter)
Are you building something awesome with next-on-netlify
? š„ Let us know and we will feature it here :)
4 years ago