README
next-on-netlify is a utility for hosting NextJS applications with Server-Side Rendering on Netlify. It wraps your NextJS application in a tiny compatibility layer, so that pages can be server-side rendered with Netlify functions.
- Demo: https://next-on.netlify.com/
- Example repository: https://github.com/FinnWoelm/next-on-netlify-demo
Table of Contents
Installation
npm install --save next-on-netlify
Setup
1. Set NextJS target to serverless
We must build our NextJS app as a serverless app. You can read more about serverless NextJS here.
It's super simple. Just create a next.config.js file and write the following:
// next.config.js
module.exports = {
// Target must be serverless
target: 'serverless'
};2. Add postbuild hook
The next-on-netlify package adds the next-on-netlify command. When we run this command, some magic happens to prepare our NextJS app for hosting on Netlify*.
We want the next-on-netlify command to run after we build our NextJS application. So let's add a postbuild hook to our package.json file:
{
"name": "my-nextjs-app",
"scripts": {
"dev": "next",
"build": "next build",
"postbuild": "next-on-netlify"
},
....
}*If you're curious about the "magic", check out the well-documented next-on-netlify.js file.
3. Configure Netlify
We're almost done! We just have to tell Netlify how to build our NextJS app, where the functions folder is located, and which folder to upload to its CDN. We do that with a netlify.toml file and the following instructions:
[build]
command = "npm run build"
functions = "out_functions"
publish = "out_publish"We're done. Let's deploy 🚀🚀🚀
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 against which next-on-netlify has been tested):
npm install -g netlify-cliThen, 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 NextJS 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/
/404.htmlNow you're all set.
From now on, whenever you want to preview your application locally, just run:
npm run build: This will runnext buildto build your NextJS app andnext-on-netlifyto prepare your NextJS 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:
_redirectsnext-on-netlifyredirectsnetlify.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
Preview Mode
NextJS Preview Mode does not work on pages that are pre-rendered (pages with getStaticProps). Netlify currently does not support cookie-based redirects, which are needed for supporting preview mode on pre-rendered pages. Preview mode works correctly on any server-side-rendered pages (pages with getInitialProps or getServerSideProps). See: Issue #10
Fallbacks for Pages with getStaticPaths
Fallback pages behave differently with next-on-netlify than they do with NextJS. On NextJS, when navigating to a path that is not defined in getStaticPaths, it first displays the fallback page. NextJS 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
Showcase
The following sites are built with next-on-netlify:
Are you building something awesome with next-on-netlify? 🔥 Let me know and we will feature it here :)
Credits
📣 Shoutout to @mottox2 (a pioneer of hosting NextJS 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: