Free Event Series! Navigating Hypergrowth: Conversations with leaders who’ve seen success at scale. Register now.

By Cassidy Williams in Guides & Tutorials

Migrating an existing Next.js project to Netlify

Hellloooo!

So, you have a Next.js project that works flawlessly, and you want to put it on Netlify for the first time. Fun! Here’s some things you might have to do.

Add a netlify.toml file

You’ll need a netlify.toml file added at the top level of your project to make sure everything is imported correctly.

[build]
  command = "npm run build"
  publish = "out"

You can also do this in the Netlify UI if you don’t want to make this file by filling in the build command and publish directory!

Basic build settings on Netlify, with command npm run build and directory out

If you aren’t using the defaults for your Next.js publish or functions directory, you can change the values here! For example:

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

If you would like to customize even more build settings, check out the docs for more information on this!

Update your next.config.json

If you have a next.config.json file, you need to add target: serverless to it. If you don’t have one, you don’t need to do this. The reason for this is because we don’t want to mess up any existing next.config.js content you might already have!

Also, your redirects and rewrites in this file will need to be moved. Which brings us to…

Redirects

You can define your custom redirects and rewrites in a _redirects file at the top level of your project (or you can use redirects in your netlify.toml file, too). There’s more information for how these can be structured in the docs!

Anything else?

Honestly, probably not. Each of these steps are optional, depending on your project! We auto-install the Essential Next.js Build Plugin to all new Next.js projects on the platform, which will enable server-side rendering and other framework-specific features in your builds. If you have any problems with it, you can uninstall it, or file an issue on the repo, or ask questions in our community!

What if I don’t have an existing Next.js project?

Been there! Here’s a starter project for ya to get going:

Deploy to Netlify

(Clicking this button will deploy a Next.js starter project to Netlify, and clone it to your chosen Git provider, PLUS because it’s brand new, you can completely ignore the previous parts of this post)