Skip to content

Configuration Reference (nextdeploy.yml) ​

The nextdeploy.yml file is the central source of truth for your Next.js application infrastructure. It lives in the root directory of your project repository.


Complete Example ​

yaml
version: "1.0"

# Target type: "vps" | "serverless"
target_type: vps

# ── App Metadata ────────────────────────────────────────────────
app:
  name: my-app                  # 3-63 lowercase alphanumeric chars and hyphens
  environment: production       # development | staging | production
  domain: app.example.com       # Public custom domain
  port: 3000                    # Internal application port
  gosidecar:
    enabled: true               # Enable Go sidecar for VPS
    image_optimization: true    # Enable Go image transcoding
    isr_cache: true             # Cache prerendered RSC payloads
    max_image_workers: 4

# ── VPS Deployment Target ───────────────────────────────────────
deployment:
  server:
    host: 203.0.113.10          # Server IPv4 or hostname
    user: deploy                # SSH deployment user
    ssh_key: ~/.ssh/id_ed25519  # Local path to private SSH key
    use_sudo: true              # Execute system commands with sudo
  healthcheck:
    path: /api/health           # Healthcheck endpoint
    interval: 30s
    timeout: 5s
    retries: 3
  resources:
    memory_max: 1024M           # Linux cgroup v2 memory limit
    cpu_quota: 150%

# ── Serverless Deployment Target (Optional) ─────────────────────
# Used when target_type is set to "serverless"
serverless:
  provider: cloudflare          # "cloudflare" | "aws"
  cloudflare:
    account_id: ${CLOUDFLARE_ACCOUNT_ID}
    api_token: ${CLOUDFLARE_API_TOKEN}
    zone_name: example.com
    compatibility_date: "2024-09-23"
    resources:
      kv:
        - name: CACHE_KV
      d1:
        - name: primary_db
          binding: DB
      queues:
        - name: email-queue
          binding: QUEUE
  aws:
    region: us-east-1
    memory_size: 1024           # Lambda memory in MB
    timeout: 30                 # Timeout in seconds

# ── Database & Migrations ───────────────────────────────────────
database:
  type: postgres                # postgres | mysql
  host: 10.0.0.5
  port: 5432
  name: app_prod
  username: app_user
  password: ${DB_PASSWORD}
  migrate_on_deploy: true       # Run migrations on deploy

# ── Logging & Monitoring ────────────────────────────────────────
logging:
  enabled: true
  provider: nextdeploy
  stream_logs: true

monitoring:
  enabled: true
  cpu_threshold: 80
  memory_threshold: 80
  alert:
    slack_webhook: ${SLACK_WEBHOOK_URL}
    notify_on:
      - crash
      - healthcheck_failed

Field Specifications ​

Root Fields ​

FieldTypeDescription
versionstringConfiguration schema version ("1.0").
target_typestringDeployment target: "vps" or "serverless".

app ​

FieldTypeRequiredDescription
namestringYesUnique application identifier (^[a-z0-9-]+$, 3-63 characters).
environmentstringYesEnvironment name (production, staging, development).
domainstringYesPublic domain name where Caddy or CloudFront/Cloudflare will route traffic.
portintegerNoInternal port for the Node.js HTTP server (default: 3000).
gosidecar.enabledbooleanNoEnables the high-performance Go sidecar for VPS targets (default: false).
gosidecar.image_optimizationbooleanNoOffload Next.js image resizing and WebP/AVIF generation to Go sidecar.
gosidecar.isr_cachebooleanNoEnable Go sidecar caching of static HTML and RSC payloads.

deployment.server (VPS Target) ​

FieldTypeRequiredDescription
hoststringYesVPS IP address or hostname accessible over SSH.
userstringYesRemote SSH username (e.g. ubuntu or deploy).
ssh_keystringYesLocal path to SSH private key.
use_sudobooleanNoWhether commands run with sudo (default: false).

deployment.healthcheck ​

FieldTypeDefaultDescription
pathstring"/api/health"Route to probe before completing atomic cutover. Must return HTTP 200.
intervalduration30sHealth check interval.
timeoutduration5sTimeout for each health check probe.
retriesinteger3Number of probe retries before marking deploy as failed.

serverless.cloudflare ​

FieldTypeDescription
account_idstringCloudflare Account ID. Can use ${CLOUDFLARE_ACCOUNT_ID} env var.
api_tokenstringCloudflare API Token with Workers, R2, and DNS permissions.
compatibility_datestringCloudflare Workers compatibility date (e.g. "2024-09-23").
resourcesobjectDeclarative bindings for KV, D1 databases, Queues, Hyperdrive, Vectorize, AI Gateway.

Environment Variable Substitution ​

nextdeploy.yml natively supports environment variable interpolation using ${VARIABLE_NAME} syntax. Unresolved variables can be populated via local .env or CI secret stores.

Released under the MIT License.