git:20260223.c6d4db1 to git:20260323.802c8e8

---

name: nextjs-deployment

description: Provides comprehensive patterns for deploying Next.js applications to production. Use when configuring Docker containers, setting up GitHub Actions CI/CD pipelines, managing environment variables, implementing preview deployments, or setting up monitoring and logging for Next.js applications. Covers standalone output, multi-stage Docker builds, health checks, OpenTelemetry instrumentation, and production best practices.

allowed-tools: Read, Write, Edit, Bash

---

# Next.js Deployment

Deploy Next.js applications to production with Docker, CI/CD pipelines, and comprehensive monitoring.

## When to Use

Activate when user requests involve:

- "Deploy Next.js", "Dockerize Next.js", "containerize"

- "GitHub Actions", "CI/CD pipeline", "automated deployment"

- "Environment variables", "runtime config", "NEXT_PUBLIC"

- "Preview deployment", "staging environment"

- "Monitoring", "OpenTelemetry", "tracing", "logging"

- "Health checks", "readiness", "liveness"

- "Production build", "standalone output"

- "Server Actions encryption key", "NEXT_SERVER_ACTIONS_ENCRYPTION_KEY"

## Quick Reference

### Output Modes

| Mode | Use Case | Command |

|------|----------|---------|

| `standalone` | Docker/container deployment | `output: 'standalone'` |

| `export` | Static site (no server) | `output: 'export'` |

| (default) | Node.js server deployment | `next start` |

### Environment Variable Types

| Prefix | Availability | Use Case |

|--------|--------------|----------|

| `NEXT_PUBLIC_` | Build-time + Browser | Public API keys, feature flags |

| (no prefix) | Server-only | Database URLs, secrets |

| Runtime | Server-only | Different values per environment |

### Key Files

| File | Purpose |

|------|---------|

| `Dockerfile` | Multi-stage container build |

| `.github/workflows/deploy.yml` | CI/CD pipeline |

| `next.config.ts` | Build configuration |

| `instrumentation.ts` | OpenTelemetry setup |

| `src/app/api/health/route.ts` | Health check endpoint |

## Instructions

```typescript

// next.config.ts

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {

output: 'standalone',

poweredByHeader: false,

}

export default nextConfig

```

```dockerfile

# syntax=docker/dockerfile:1

FROM node:20-alpine AS base

FROM base AS deps

RUN apk add --no-cache libc6-compat

WORKDIR /app

FROM base AS builder

WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules

COPY . .

FROM base AS runner

WORKDIR /app

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

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

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

USER nextjs

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \

CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => r.statusCode === 200 ? process.exit(0) : process.exit(1))"

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

```

```yaml

# .github/workflows/deploy.yml

name: Build and Deploy

on:

push:

branches: [main, develop]

env:

REGISTRY: ghcr.io

IMAGE_NAME: ${{ github.repository }}

jobs:

build:

runs-on: ubuntu-latest

permissions:

contents: read

packages: write

steps:

with:

registry: ${{ env.REGISTRY }}

username: ${{ github.actor }}

password: ${{ secrets.GITHUB_TOKEN }}

uses: docker/metadata-action@v5

with:

images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

with:

context: .

push: true

tags: ${{ steps.meta.outputs.tags }}

cache-from: type=gha

cache-to: type=gha,mode=max

build-args: |

GIT_HASH=${{ github.sha }}

NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=${{ steps.generate-key.outputs.key }}

```

```typescript

// src/lib/env.ts

export function getEnv() {

return {

databaseUrl: process.env.DATABASE_URL!,

apiKey: process.env.API_KEY!,

publicApiUrl: process.env.NEXT_PUBLIC_API_URL!,

}

}

export function validateEnv() {

const required = ['DATABASE_URL', 'API_KEY', 'NEXT_PUBLIC_API_URL']

const missing = required.filter((key) => !process.env[key])

if (missing.length > 0) {

throw new Error(`Missing required environment variables: ${missing.join(', ')}`)

}

}

```

```typescript

// src/app/api/health/route.ts

import { NextResponse } from 'next/server'

export const dynamic = 'force-dynamic'

export async function GET() {

const checks = {

status: 'healthy',

timestamp: new Date().toISOString(),

version: process.env.npm_package_version || 'unknown',

uptime: process.uptime(),

}

}

```

```typescript

// instrumentation.ts

import { registerOTel } from '@vercel/otel'

export function register() {

registerOTel({

serviceName: process.env.OTEL_SERVICE_NAME || 'next-app',

})

}

```

```bash

openssl rand -base64 32

```

## Best Practices

```typescript

// next.config.ts

output: 'standalone',

poweredByHeader: false,

compress: true,

generateBuildId: async () => process.env.GIT_HASH || 'build',

}

export default nextConfig

```

```yaml

version: '3.8'

services:

app:

build: .

ports:

- "3000:3000"

environment:

- DATABASE_URL=postgresql://db:5432/myapp

- NEXT_PUBLIC_API_URL=http://localhost:3000/api

```

## Constraints and Warnings

### Constraints

- Standalone output requires Node.js 18+

- Server Actions encryption key must be consistent across all instances

- Runtime environment variables only work with `output: 'standalone'`

- OpenTelemetry requires instrumentation.ts at project root

### Warnings

- **Never** use `NEXT_PUBLIC_` prefix for sensitive values

- Always set `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` for multi-server deployments

- Without health checks, orchestrators may send traffic to unhealthy instances

- Runtime env vars don't work with static export (`output: 'export'`)

## References

- **[references/docker-patterns.md](references/docker-patterns.md)** - Advanced Docker configurations, multi-arch builds, optimization

- **[references/github-actions.md](references/github-actions.md)** - Complete CI/CD workflows, testing, security scanning

- **[references/monitoring.md](references/monitoring.md)** - OpenTelemetry, logging, alerting, dashboards

- **[references/deployment-platforms.md](references/deployment-platforms.md)** - Platform-specific guides (Vercel, AWS, GCP, Azure)