Next.js Deployment

Next.js Deployment: Shipping Production Apps Safely

Next.js deployment packages your App Router pages, Server Components, and static assets into an optimized production build. Always run a local production build first to catch TypeScript errors and missing environment variables before releasing.

npm run build
npm run start

The next build command compiles server bundles, optimizes images, and pre-renders static pages into the .next/ directory.

Option 1: Managed Hosting on Vercel

Vercel maintains Next.js and supports zero-config builds, automatic preview URLs for pull requests, and global edge caching.

1. Push your repository to GitHub, GitLab, or Bitbucket.
2. Import the repository in the Vercel dashboard.
3. Add your production environment variables and deploy.

Option 2: Self-Hosting on a Node.js Server

You can run Next.js on any Linux virtual machine running Node.js 18.18+ behind Nginx or Caddy. Use PM2 to restart the server automatically if it exits.

npm ci --omit=dev
npm run build
pm2 start npm --name "web-app" -- start

Option 3: Standalone Docker Container

Enable output: 'standalone' in next.config.ts so Next.js traces only required runtime dependencies, shrinking Docker image sizes sharply.

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'standalone',
};

export default nextConfig;

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

COPY .next/standalone ./
COPY .next/static ./.next/static
COPY public ./public

EXPOSE 3000
CMD ["node", "server.js"]

Common Mistakes

• Skipping npm run build locally before pushing: Development mode (npm run dev) skips strict TypeScript and static prerender checks that fail in CI.
• Forgetting .next/static and public/ in Docker standalone images: Standalone output requires copying those two folders manually so CSS and public images load.
• Running next start on multiple containers without shared image/cache storage: Configure a shared Redis cache handler or CDN if you scale standalone pods horizontally.

Frequently Asked Questions

Can I export a Next.js app as pure static HTML files?

Yes, set output: 'export' in next.config.ts, though dynamic Server Actions, Middleware, and on-demand image optimization will not run without a server.

Why do environment variables fail at runtime in Docker?

NEXT_PUBLIC_* variables are baked in at next build time, whereas server-only variables are read at runtime from the container environment.

How do I run database migrations during deployment?

Execute your migration command in a CI step or release hook before starting the new Next.js server process.