Next.js Production Deployment Guide: Static, SSR, and API Routes

Next.js is one of the most versatile React frameworks available, supporting static site generation (SSG), server-side rendering (SSR), and API routes in a single codebase. Deploying it correctly to production requires understanding which mode your app uses and matching that to the right hosting strategy.

This guide walks you through deploying a Next.js application to production using Docker and PandaStack.

Understanding Next.js Output Modes

Next.js has two primary output modes relevant to deployment:

Static Export — pages are pre-rendered to plain HTML/CSS/JS at build time. No Node.js server is required. Ideal for marketing sites, blogs, and documentation.

Standalone Server — Next.js runs a Node.js server that handles SSR, ISR, and API routes at request time. Requires a container or server.

You configure this in next.config.js:

// next.config.js — static export
const nextConfig = {
  output: 'export',
  trailingSlash: true,
}

module.exports = nextConfig

// next.config.js — standalone server (SSR + API routes)
const nextConfig = {
  output: 'standalone',
}

module.exports = nextConfig

Deploying a Next.js Static Export

For static exports, the build produces an out/ directory. Connect your GitHub repository to [PandaStack](https://pandastack.io) and add a pandastack.json at your project root:

{
  "type": "static",
  "buildCommand": "npm run build",
  "outputDir": "out"
}

PandaStack reads this file on every deploy, runs your build command, and serves the out/ directory from its global CDN edge network. No server configuration required.

Deploying Next.js SSR with Docker

For SSR or apps with API routes, you need a container. Create a production-ready Dockerfile using Next.js's standalone output:

FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

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

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

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

This multi-stage build keeps the final image small and production-ready.

Configuring pandastack.json for Docker Deployments

For container deployments, your pandastack.json should specify a health check path so PandaStack knows when your container is healthy and ready to receive traffic:

{
  "type": "container",
  "healthCheckPath": "/api/health"
}

Add a simple health endpoint to your Next.js app:

// pages/api/health.js
export default function handler(req, res) {
  res.status(200).json({ status: 'ok' })
}

Setting Up Environment Variables

Next.js distinguishes between server-side and client-side environment variables. Variables prefixed with NEXT_PUBLIC_ are embedded at build time and exposed to the browser. All others remain server-side only.

Configure your production environment variables in the PandaStack dashboard at [dashboard.pandastack.io](https://dashboard.pandastack.io):

# Server-side only (safe for secrets)
DATABASE_URL=postgresql://user:pass@host:5432/mydb
NEXTAUTH_SECRET=your-secret-here

# Client-side (exposed to browser — never put secrets here)
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_ANALYTICS_ID=UA-XXXXX

Connecting GitHub for Automatic Deployments

PandaStack's GitHub integration enables automatic deployments on every push to your production branch. Connect your repository from the dashboard, select your target branch (typically main), and every push will trigger a fresh build and deploy automatically.

# Install the PandaStack CLI
npm install -g @pandastack/cli

# Deploy manually from your terminal
panda deploy

Setting Up a Production Database

Most Next.js SSR apps need a database. Provision a managed PostgreSQL or MySQL database directly from the PandaStack dashboard under the Databases section. PandaStack provides managed PostgreSQL, MySQL, Redis, and MongoDB instances — no separate database hosting account needed.

Copy the connection string from the dashboard and add it as the DATABASE_URL environment variable in your project settings.

Production Checklist

Before you go live, verify:

NODE_ENV=production is set in your container environment
All secrets are stored as environment variables, not in source code
healthCheckPath is configured and returning HTTP 200
Your next.config.js sets the correct output mode
GitHub integration is connected and auto-deploy is tested

Monitoring and Logs

After deploying, check your application logs from the PandaStack dashboard to confirm the server started correctly. Look for the Next.js startup message confirming the server is listening on the expected port.

Next.js in production outputs structured logs for errors and page renders. Use these alongside your database and API monitoring to catch issues before users do.

For full documentation on PandaStack deployment options, visit [docs.pandastack.io](https://docs.pandastack.io).

Next.js Production Deployment Guide: Static, SSR, and API Routes