Repository files navigation

Great news for everyone using NextJS on Netlify: Netlify has decided toofficially adopt thenext-on-netlify npm package and to hire an engineer tosupport the development of this package. This will makenext-on-netlifyeven better and ensure that using NextJS with Netlify is as seamless andfeature-complete as possible!

The package will remain completely open source and@cassidoo, thePrincipal Developer Experience Engineer at Netlify, will be joiningnext-on-netlify as a core maintainer.

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

• Installation
• Setup
  • 1. Set NextJS target to serverless
  • 2. Add postbuild hook
  • 3. Configure Netlify
• Optional Extras
  • Preview Locally
  • Custom Netlify Redirects
  • Custom Netlify Functions
• Caveats
  • Preview Mode
  • Fallbacks for Pages withgetStaticPaths
• Showcase
• Credits

npm install --save next-on-netlify

We must build our NextJS app as a serverless app. You can read more about serverless NextJShere.

It's super simple. Just create anext.config.js file and write the following:

// next.config.jsmodule.exports={// Target must be serverlesstarget:"serverless",};

The next-on-netlify package adds thenext-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-documentednext-on-netlify.js file.

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 anetlify.toml file and the following instructions:

[build]command   ="npm run build"functions ="out_functions"publish   ="out_publish"

We're done. Let's deploy 🚀🚀🚀

I recommend you still usenext dev to build and preview your application locally.

But if you want to emulate the Netlify deployment on your computer, you can also runnext-on-netlify locally and then usenetlify-cli to preview the result.

First, install the latest version ofnetlify-cli (you can alsolook 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 yournetlify.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-detectionframework ="#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:

1. npm run build: This will runnext build to build your NextJS app andnext-on-netlify to prepare your NextJS app for compatibility with Netlify
2. netlify dev: This will emulate Netlify on your computer and let you preview your app onhttp://localhost:8888.

You can define custom redirects in a_redirects and/or in yournetlify.toml file.The precedence of these rules are:

• _redirects
• next-on-netlify redirects
• netlify.toml

Read more about Netlify redirects here.

next-on-netlify creates one Netlify Function for each of yourSSR 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.

NextJS Preview Mode does not work on pages that are pre-rendered (pages withgetStaticProps). 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 withgetInitialProps orgetServerSideProps). See:Issue #10

Fallback pages behave differently withnext-on-netlify than they do with NextJS. On NextJS, when navigating to a path that is not defined ingetStaticPaths, it first displays the fallback page. NextJS then generates the HTML in the background and caches it for future requests.

Withnext-on-netlify, when navigating to a path that is not defined ingetStaticPaths, 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

The following sites are built withnext-on-netlify:

opinionatedreact.com (via Twitter)

missionbit.org (#18)

Are you building something awesome withnext-on-netlify? 🔥 Let us know and we will feature it here :)

📣 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:

• @spencewood
• @alxhghs
• @gamliela
• @wei
• @laugharn
• @rajington
• @etrepum
• @jonasbuntinx
• @joostmeijles