Beginner10 minutesUpdated 2026-03-01

Next.js is one of the most popular React frameworks, and Netlify provides first-class support for it. With the @netlify/plugin-nextjs runtime, you get full support for Server-Side Rendering (SSR), Incremental Static Regeneration (ISR), API routes, middleware, and image optimization — all running on Netlify's edge network.

Prerequisites

Node.js 18 or later installed
A Next.js project (App Router or Pages Router)
A Netlify account
Git repository (GitHub, GitLab, or Bitbucket)

Step 1: Push your Next.js project to Git

Make sure your Next.js project is in a Git repository and pushed to GitHub, GitLab, or Bitbucket. Netlify deploys directly from your repository, so every push to your main branch will trigger a new deploy.

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/your-user/your-repo.git
git push -u origin main

Step 2: Connect your repository to Netlify

Log in to Netlify, click 'Add new site' > 'Import an existing project', and select your Git provider. Choose the repository containing your Next.js app.

You can also use the Netlify CLI with 'netlify init' to connect your repo from the terminal.

Step 3: Configure build settings

Netlify automatically detects Next.js projects and sets the correct build command and publish directory. Verify these settings are correct:

Build settings

Build command: next build
Publish directory: .next

The @netlify/plugin-nextjs runtime is automatically installed. You don't need to add it manually.

Step 4: Set environment variables

If your project uses environment variables, add them in Netlify under Site settings > Environment variables. Variables prefixed with NEXT_PUBLIC_ will be available in the browser.

Example environment variables

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://...
NEXT_PUBLIC_SITE_URL=https://your-site.netlify.app

Step 5: Deploy your site

Click 'Deploy site'. Netlify will clone your repository, install dependencies, run 'next build', and deploy the output. Your first deploy typically takes 1-3 minutes.

After the initial deploy, subsequent deploys are faster thanks to Netlify's build cache.

Step 6: Set up a custom domain

Once deployed, your site is live at a .netlify.app URL. To add a custom domain, go to Site settings > Domain management > Add custom domain. Netlify automatically provisions a free SSL certificate.

your-site.netlify.app → yourdomain.com

netlify.toml Configuration

This netlify.toml configures Netlify to build your Next.js app with the correct command and output directory. The @netlify/plugin-nextjs plugin enables SSR, ISR, API routes, and middleware support.

netlify.toml

[build]
  command = "next build"
  publish = ".next"

[[plugins]]
  package = "@netlify/plugin-nextjs"

Common Errors

Error: Cannot find module 'next'

Cause: Dependencies weren't installed before the build command ran, or the node_modules directory is cached incorrectly.

Fix: Clear the build cache in Netlify (Deploys > Trigger deploy > Clear cache and deploy site) and ensure 'next' is in your package.json dependencies, not devDependencies.

Build exceeded maximum allowed runtime

Cause: The build is taking too long, often due to large static generation or unoptimized images.

Fix: Consider using ISR instead of full static generation for pages with many routes. Add 'images.unoptimized: true' in next.config.js if image optimization is causing timeouts.

Error: ENOENT: no such file or directory

Cause: File paths that work on your local machine (case-insensitive) fail on Netlify's Linux build environment (case-sensitive).

Fix: Check all import paths and file references for correct casing. For example, 'components/Header.tsx' and 'components/header.tsx' are different files on Linux.

Pro Tips

Use Netlify's deploy previews to test changes before merging to production. Every pull request gets its own preview URL.

Enable the Next.js runtime caching by setting the environment variable NETLIFY_NEXT_PLUGIN_SKIP to 'false' (it's enabled by default).

For large Next.js sites, use on-demand ISR with Netlify's cache invalidation API to update specific pages without rebuilding the entire site.

Monitor your deploys on the go with the Netli.fyi app — get push notifications for build failures and deploy completions.

Use Netlify Functions alongside your Next.js API routes for background tasks or scheduled jobs that go beyond what API routes support.

Deploy Next.js to Netlify