Useful Cheatsheets
Build / Code / Next.js

Next.js Deployment

Deploy a Next.js app to Vercel, a Node.js server, a Docker container, or static hosting.

TL;DR

  1. Build with next build, then serve the app with next start.
  2. Set output: 'standalone' to produce a small server for Docker.
  3. Set output: 'export' to generate a fully static site.
Jump to section

Build and Run

    next build

    Create the optimized production build and catch type and prerender errors.

    npm run build
    next start

    Serve the production build with the built-in Node.js server.

    npm run start

# or choose a port
npx next start -p 8080
    Build-Time Variables

    Provide public variables during the build, because they are inlined into the code.

    NEXT_PUBLIC_API_URL="https://api.example.com" \
  npm run build

Vercel

    git push

    Connect the repository once, then every push to main deploys automatically.

    git push origin main
# Vercel builds and deploys the commit
    Preview Deployments

    Push a branch and open a pull request to get a private preview URL.

    git checkout -b new-feature
git push origin new-feature
# the pull request gets its own URL
    vercel

    Deploy from the terminal with the Vercel command-line tool.

    npm install -g vercel
vercel          # preview deployment
vercel --prod   # production deployment

Docker and Standalone

    output: 'standalone'

    Produce a minimal server folder that needs no separate node_modules install.

    // next.config.ts
const nextConfig = {
  output: 'standalone',
};
    Copy Static Files

    Add the public and static folders, which the standalone output leaves out.

    cp -r public .next/standalone/
cp -r .next/static .next/standalone/.next/
node .next/standalone/server.js
    Dockerfile

    Build in one stage and copy only the standalone output into the final image.

    FROM node:22-alpine AS build
WORKDIR /app
COPY . .
RUN npm ci && npm run build

FROM node:22-alpine
WORKDIR /app
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
CMD ["node", "server.js"]
    HOSTNAME and PORT

    Listen on all interfaces inside a container so the host can reach the app.

    ENV HOSTNAME=0.0.0.0
ENV PORT=3000
EXPOSE 3000

Static Export

    output: 'export'

    Generate plain HTML, CSS, and JavaScript files with no server required.

    const nextConfig = {
  output: 'export',
};
    out

    Find the exported site in the out folder and upload it to any static host.

    npm run build
npx serve out
    images.unoptimized

    Turn off the image optimizer, since a static export has no server to run it.

    const nextConfig = {
  output: 'export',
  images: { unoptimized: true },
};

Tips

  1. Run npm run build locally before every deploy, because type errors and prerender failures stop the production build.
  2. Put a reverse proxy such as nginx in front of next start, so it handles slow connections and malformed requests.

Warnings

  1. The standalone server does not include public or .next/static, so copy both folders into the output before starting it.
  2. A static output: 'export' build cannot use Server Functions, cookies, or the proxy file, because no server runs.

In Practice

FAQ