Skip to main content

Documentation Index

Fetch the complete documentation index at: https://next-safe-env.dev/llms.txt

Use this file to discover all available pages before exploring further.

next-safe-env ships a CLI you can run with npx - no install required. 
npx next-safe-env <command>
npx next-safe-env --help

​
check - validate before you deploy

Validates the current environment against your schema without starting the app. Useful in CI pipelines to gate deployments before they reach production. 
npx next-safe-env check [file]

​
Arguments

ArgumentDefaultDescription
filesrc/env.js, then dist/env.jsPath to the compiled env file to validate

​
Exit codes

CodeMeaning
0All environment variables are valid
1One or more variables are missing or invalid
The command imports your env file in an isolated child process. Because createEnv runs at import time, any validation failure triggers the same formatted error output you’d see at startup - then the process exits with code 1.

​
Examples

# Auto-discover src/env.js or dist/env.js
npx next-safe-env check

# Point at a specific compiled file
npx next-safe-env check ./dist/env.js

# In a CI step (non-zero exit halts the pipeline)
npx next-safe-env check && echo "Env OK, deploying..."

​
Sample output on failure

[next-safe-env] Checking src/env.js...

[next-safe-env] Environment validation failed - 2 error(s):

  ✗ DATABASE_URL     - Expected valid URL. Got: "postgres-localhost"
  ✗ JWT_SECRET       - Expected length >= 32. Got length: 12

  Server vars:  1 valid, 2 invalid
  Client vars:  2 valid, 0 invalid

  Set the correct values in your .env file or deployment environment and restart.

[next-safe-env] ✗ Validation failed.
check imports your compiled .js file - not the .ts source. Build your project first (npm run build) or use a TypeScript runner like tsx:
tsx node_modules/.bin/next-safe-env check ./src/env.ts

​
init - interactive scaffold

Generates src/env.ts and .env.example by asking which variables your app needs and what type each one should be. 
npx next-safe-env init [options]

​
Options

OptionDefaultDescription
--output <path>src/app/env.ts (Next.js App Router), app/env.ts (Next.js Pages Router), src/env.ts (all others)Output path for the generated env.ts

​
What it asks

  1. Framework - auto-detected from package.json (checks for next, vite, @cloudflare/workers-types, etc.). If detected, you’re asked to confirm; if not, you choose from Next.js, Node.js, Vite, or Edge Runtime. The framework determines the adapter and client-var prefix.
  2. Server-side variables - name, type, optional flag, default value, and (for str) allowed values
  3. Client-side variables - same prompts; variable names are auto-prefixed (NEXT_PUBLIC_ or VITE_) if you omit the prefix
  4. Output file path
  5. Whether to generate .env.example

​
Example session

$ npx next-safe-env init

next-safe-env init - Interactive scaffold

Detected adapter: Next.js
Use Next.js? [y/n] (y):

Server-side variables (press Enter with empty name to finish):

  Variable name (or Enter to finish): DATABASE_URL
  Type [str/url/num/port/bool] (str): url
  Optional? [y/n] (n): n
  Default value (Enter for none):

  Variable name (or Enter to finish): PORT
  Type [str/url/num/port/bool] (str): port
  Optional? [y/n] (n): n
  Default value (Enter for none): 3000

  Variable name (or Enter to finish):

Client-side variables (must start with NEXT_PUBLIC_, press Enter to finish):

  Variable name (or Enter to finish): NEXT_PUBLIC_APP_NAME
  Type [str/url/num/port/bool] (str):
  Optional? [y/n] (n): n
  Default value (Enter for none): My App
  Allowed values, comma-separated (Enter to skip):

  Variable name (or Enter to finish):

Output file [src/app/env.ts]:
Generate .env.example? [y/n] (y): y

✓ Generated src/app/env.ts
✓ Generated .env.example
If the adapter cannot be auto-detected, the framework menu is shown instead:
Which framework are you using?
  1. Next.js
  2. Node.js
  3. Vite
  4. Edge Runtime

>

​
Generated src/app/env.ts

import { createEnv, port, str, url } from 'next-safe-env'

export const env = createEnv({
  server: {
    DATABASE_URL: url(),
    PORT: port().default(3000),
  },
  client: {
    NEXT_PUBLIC_APP_NAME: str().default('My App'),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    PORT: process.env.PORT,
    NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME,
  },
  adapter: 'nextjs',
})

​
.env.example generation

Running init with the .env.example prompt answered y produces a commented template alongside src/env.ts. Each variable gets an inline comment describing its type, whether it is required, any constraints, and its default value - so new contributors know exactly what to fill in.

​
Example .env.example

# ---- Server-side variables ----

# DATABASE_URL - required valid URL
DATABASE_URL=

# PORT - required port number (1–65535)
# Default: 3000
PORT=3000

# NODE_ENV - required string
# Allowed values: development | production | test
NODE_ENV=

# ---- Client-side variables ----

# NEXT_PUBLIC_APP_NAME - required string
# Default: My App
NEXT_PUBLIC_APP_NAME=My App