Environment Variables

Nextly reads environment variables for database connections, authentication, storage, email, and other runtime settings. Most live in the central env schema (packages/nextly/src/shared/lib/env.ts); storage adapter env vars are per-adapter and read by the adapter packages directly.

Copy .env.example to .env and fill in values:

cp .env.example .env

Canonical .env.example

The base template templates/base/.env.example ships the minimum required variables:

# Nextly Configuration
# Generated by create-nextly-app

# Database Configuration
DB_DIALECT=postgresql
DATABASE_URL=postgresql://user:password@localhost:5432/nextly_dev

# Authentication (REQUIRED)
# Generate with: openssl rand -base64 32
NEXTLY_SECRET=change-me-generate-a-secure-secret

# Application URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Development diagnostics (opt-in — see below)
# NEXTLY_DEV_DIAGNOSTICS=1

# Storage (per-adapter — see "Storage" section below)

The create-nextly-app scaffolder fills in DB_DIALECT, DATABASE_URL, and an auto-generated 32-byte base64 NEXTLY_SECRET for you. For a production deployment, regenerate NEXTLY_SECRET with:

openssl rand -base64 32

Database

Source: packages/nextly/src/shared/lib/env.ts.

Connection-string formats

# PostgreSQL (recommended for production)
DATABASE_URL=postgresql://user:password@localhost:5432/nextly_dev

# MySQL
DATABASE_URL=mysql://root:root@localhost:3306/nextly_dev

# SQLite (development / single-instance only)
DATABASE_URL=file:./dev.db

Runtime

Development diagnostics

An error response is deliberately generic: it carries a code, a public message and a request id, and withholds the log context and the underlying cause so a response cannot disclose driver output, table names or internal paths. That is right for a deployed app and unhelpful while you are building, where the detail you need is exactly what was withheld.

With this set, an error in development also carries:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred.",
    "requestId": "req_01HQ...",
    "_devDiagnostics": {
      "logContext": { "collectionName": "posts", "entryId": "abc123" },
      "cause": "duplicate key value violates unique constraint posts_slug_key",
      "flattened": [{ "code": "CONFLICT", "logContext": { "field": "slug" } }]
    }
  }
}

flattened lists errors that were rebuilt on the way to the boundary, which is what makes an unexpected failure name itself instead of looking like every other one.

Why it is opt-in rather than on by default. The gate requires two independent signals: NODE_ENV must be development and this flag must be 1. The second exists precisely because the first can be wrong — nextly ships pre-built and stays external to your build, so NODE_ENV is a runtime value a deployment can carry by mistake.

A default that shipped in .env would be true in exactly that case, which is the one the second signal guards against, collapsing two independent signals back into one. So create-nextly-app writes the setting commented out with this explanation: discoverable, and never enabled by a file that travels with your app.

Uncomment it in your local .env — not in a file you deploy — and keep it out of any environment where NODE_ENV might not be what you expect.

Authentication

Nextly uses a custom JWT auth system (access + refresh tokens, sessions, API keys, RBAC). There is no OAuth.

Rotating NEXTLY_SECRET

Rotating the secret re-keys everything derived from it, and the values already written do not move. For most of them that fails loudly and is fine — a webhook signing secret that no longer decrypts is one an operator re-enters.

The email delivery log is the exception, because it fails quietly. Each row identifies its recipient by an HMAC of their address, so after a rotation an erasure request computes a digest none of the older rows carry, matches nothing, and reports success. "No rows matched" is also what a person with no mail looks like, so nothing distinguishes the two.

List the old secret in NEXTLY_SECRET_PREVIOUS and those rows stay reachable — for lookups and for erasure — without becoming writable:

NEXTLY_SECRET=the-new-one
NEXTLY_SECRET_PREVIOUS=the-old-one,an-older-one

Two spellings, because one of them cannot express every legal secret. The comma-separated form above is the ordinary one. Use the JSON-array form when a retired secret contains a comma, or when leading or trailing whitespace is part of the key — splitting or trimming those produces a key that was never used, which matches nothing and fails in the silent direction:

# Single quotes are REQUIRED. Without them the shell strips the inner double
# quotes and the value becomes `[old,with,commas,  spaced  ]`, which is not
# JSON — it falls back to comma splitting and derives four keys that were never
# used, so lookups and erasure silently miss the rows this is meant to reach.
NEXTLY_SECRET_PREVIOUS='["old,with,commas","  spaced  "]'

The JSON form also names two generations no string can:

• null is the unkeyed generation — what an install writes when it has no NEXTLY_SECRET at all, which is only possible outside production. Rows written then carry a plain SHA-256 digest that no HMAC reproduces, so enabling a secret later strands them unless you name that generation.
• "" is a secret that really was the empty string, which is used as an HMAC key like any other.

# was unkeyed in development, now has a secret
NEXTLY_SECRET_PREVIOUS='[null]'

An empty entry in the comma form is dropped rather than rejected: a trailing comma is the likeliest way to write the list, and nothing about older, says a second key was meant. Write '[""]' when you mean it — with the outer single quotes, for the same reason.

Application URLs

Storage (per-adapter)

The default storage backend is local disk under ./public/uploads/. No env vars are needed for default storage.

Cloud adapters are opt-in. The variables below are read by the adapter packages, not by the central env schema, so they only need to exist when you actually configure that adapter in nextly.config.ts. Nothing else (env-validation, etc.) checks for them.

S3 / S3-compatible — @nextlyhq/storage-s3

Works with AWS S3, Cloudflare R2, MinIO, and DigitalOcean Spaces. The plugin accepts these values directly; the env-var names below are the conventional ones used in our examples (and what your nextly.config.ts typically references with process.env.X).

import { s3Storage } from "@nextlyhq/storage-s3";

storage: [
  s3Storage({
    bucket: process.env.S3_BUCKET!,
    region: process.env.AWS_REGION!,
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    endpoint: process.env.S3_ENDPOINT,
    forcePathStyle: process.env.S3_FORCE_PATH_STYLE === "true",
    publicUrl: process.env.S3_PUBLIC_URL,
    collections: { media: true },
  }),
];

Vercel Blob — @nextlyhq/storage-vercel-blob

Recommended for Vercel deployments.

UploadThing — @nextlyhq/storage-uploadthing

Email / SMTP

Source: packages/nextly/src/shared/lib/env.ts. Required only if you send emails (password resets, notifications). In production, if any SMTP variable is set, all four of SMTP_HOST, SMTP_USER, SMTP_PASS, SMTP_FROM must be set or the env validator throws.

For local development, the repo ships a Mailpit profile (docker compose --profile with-mailpit up -d mailpit) on host ports 1025 (SMTP) and 8025 (web UI) — see Email guide for details.

Security

These env vars are read by middleware and security helpers. None are part of the central env schema; they are read directly by the modules that use them.

Performance — permission cache

Nextly's RBAC layer ships a hybrid (in-memory LRU + database) permission cache. These env vars tune it; none are part of the central env schema — they are read directly by the permission service.

The database permission cache benefits from periodic cleanup. A typical daily cron:

0 2 * * * curl -X POST http://localhost:3000/admin/api/auth/cache/cleanup

Debug

Docker development (optional)

Used by the bundled docker-compose.yml for local Postgres / Redis / Adminer / Drizzle Studio / Mailpit setup. Not needed when connecting to an existing database.

Example .env files

Minimal production

# Runtime
NODE_ENV=production

# Database
DB_DIALECT=postgresql
DATABASE_URL=postgresql://user:password@db.example.com:5432/nextly_prod

# Auth
NEXTLY_SECRET=your-generated-secret-at-least-32-characters-long
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Storage (Vercel Blob example)
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_xxxxxxxxxxxx

Development with S3-compatible storage (MinIO)

# Database
DB_DIALECT=postgresql
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextly_dev

# Auth
NEXTLY_SECRET=dev-secret-minimum-32-characters-long-replace-in-production
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Storage (MinIO)
S3_BUCKET=nextly-dev
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://localhost:9000
S3_FORCE_PATH_STYLE=true

Next steps

• Nextly config — configure storage and security from nextly.config.ts
• Database — choose and configure PostgreSQL, MySQL, or SQLite
• Authentication guide — auth-related env vars in depth
• Deployment guide — production environment-variable checklist