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

# 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
# or
SQLITE_PATH=./dev.db

Runtime

Authentication

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

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!,
    credentials: {
      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/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