Skip to main content
A Next.js Pages Router application can be deployed to any Node.js environment, containerized with Docker, or exported as static HTML.

​
Deploying to Vercel

Vercel is the platform built by the Next.js team. It requires zero configuration.
1

Push your code to a Git provider

Push your repository to GitHub, GitLab, or Bitbucket.
2

Import your repository on Vercel

Go to vercel.com/new, import your repository, and click Deploy. Vercel detects that you are using Next.js automatically.
3

Set environment variables

In your Vercel project settings, add any environment variables from your .env.local that are needed in production.
Vercel automatically handles:
  • Building and deploying on every push.
  • Serverless Functions for API routes and SSR pages.
  • Incremental Static Regeneration on the edge.
  • Image optimization.
  • Preview deployments for pull requests.

​
Deploying to a Node.js server

For a self-hosted Node.js deployment:
1

Build the application

npm run build
This generates optimized production assets in the .next/ directory.
2

Start the production server

npm run start
By default, the server listens on port 3000. Set the PORT environment variable to change it:
PORT=8080 npm run start

​
Keeping the server running

Use a process manager like PM2 to keep your server running and restart it on crash: 
npm install -g pm2
pm2 start npm --name "my-app" -- start
pm2 save
pm2 startup

​
Deploying with Docker

Docker lets you package your application with its dependencies and deploy it anywhere containers run. Create a Dockerfile at the root of your project:
Dockerfile
FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

RUN npm run build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000
ENV PORT=3000

CMD ["node", "server.js"]
Enable standalone output in next.config.js so Next.js produces a self-contained server.js file:
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
}

module.exports = nextConfig
Build and run the container: 
docker build -t my-next-app .
docker run -p 3000:3000 my-next-app

​
Static export

If your application has no server-side requirements, you can export it as static HTML files. Static exports work without a Node.js server. Set output: 'export' in next.config.js:
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
}

module.exports = nextConfig
Then build: 
npm run build
Next.js generates a static out/ directory that you can deploy to any static hosting service (Nginx, Apache, S3, GitHub Pages, Cloudflare Pages, etc.).

​
Limitations of static export

The following features are not compatible with output: 'export' because they require a server:
  • getServerSideProps
  • API routes (pages/api/)
  • Image Optimization (unless you use a custom image loader)
  • Incremental Static Regeneration
  • Internationalized routing
If your app uses getServerSideProps or API routes, you cannot use static export. Use a Node.js server or Docker deployment instead.

​
Serving the export

To serve the out/ directory locally with Nginx: 
server {
  listen 80;
  root /var/www/my-app/out;

  location / {
    try_files $uri $uri.html $uri/ =404;
  }
}

​
Configuring for production

​
Environment variables

Set production environment variables on your hosting platform. Never commit .env.local to version control.

​
Caching

Next.js includes an HTTP response cache. For SSR pages, you can set Cache-Control headers in getServerSideProps: 
export async function getServerSideProps({ res }) {
  res.setHeader('Cache-Control', 'public, s-maxage=60, stale-while-revalidate=300')
  return { props: {} }
}
For static pages and assets, Next.js sets immutable cache headers automatically.

​
Health checks

Create a health check endpoint for load balancers:
pages/api/health.ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ status: 'ok' })
}
For a full production deployment checklist, see the Next.js production checklist.

Build docs developers (and LLMs) love

Get started for freeTalk to us