Environment Variables

This page lists every environment variable that Velox TS reads, organized by package. Most are optional since environment-aware presets provide sensible defaults — you typically only need to set secrets and service URLs.

Environment-Aware Presets

Most configuration is handled automatically by getServerConfig() and usePresets(). You only need to set secrets and service URLs - driver selection is handled by presets based on NODE_ENV.

Required Variables

Core

Variable	Description	Example
NODE_ENV	Environment mode	development, test, production
DATABASE_URL	Database connection string	file:./dev.db or postgresql://...

Authentication (Production)

Variable	Description	Minimum
JWT_SECRET	Access token signing key	32 characters
JWT_REFRESH_SECRET	Refresh token signing key	32 characters
SESSION_SECRET	Session signing key (if using sessions)	32 characters

Production Services

These are required when using usePresets() in production:

Variable	Description	Used By
REDIS_URL	Redis connection URL	Cache, Queue, Events
RESEND_API_KEY	Resend API key	Mail
S3_BUCKET	S3 bucket name	Storage

Optional Variables

Server

Variable	Description	Default
PORT	Server port	3030 (prod reads from env)
LOG_LEVEL	Logging verbosity	debug (dev), warn (prod)

Note

Host binding is handled by presets: localhost for development/test, 0.0.0.0 for production.

AWS/S3 Storage

Variable	Description	Default
AWS_REGION	AWS region	us-east-1
AWS_ACCESS_KEY_ID	AWS access key	-
AWS_SECRET_ACCESS_KEY	AWS secret key	-

SMTP Mail (Alternative to Resend)

When using SMTP driver instead of Resend:

Variable	Description	Default
SMTP_HOST	SMTP server host	-
SMTP_PORT	SMTP server port	587
SMTP_USER	SMTP username	-
SMTP_PASS	SMTP password	-

Example .env Files

Development

.env

NODE_ENV=development

# Database (SQLite for dev)
DATABASE_URL=file:./dev.db

# Auth (use secure values in production!)
JWT_SECRET=dev-jwt-secret-min-32-characters-long
JWT_REFRESH_SECRET=dev-refresh-secret-min-32-chars-here

# Optional: Override log level
LOG_LEVEL=debug

Production

.env.production

NODE_ENV=production

# Database (PostgreSQL)
DATABASE_URL=postgresql://user:password@host:5432/myapp?sslmode=require

# Auth (generate with: openssl rand -base64 48)
JWT_SECRET=<secure-random-secret-min-32-chars>
JWT_REFRESH_SECRET=<secure-random-secret-min-32-chars>
SESSION_SECRET=<secure-random-secret-min-32-chars>

# Redis (for cache, queue, events)
REDIS_URL=redis://user:password@host:6379

# Mail (Resend)
RESEND_API_KEY=re_xxxxxxxxxxxxx

# Storage (S3)
S3_BUCKET=your-bucket
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

# Optional: Override defaults
PORT=8080
LOG_LEVEL=info

Generating Secrets

# Generate a secure random secret (Node.js)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Generate using OpenSSL
openssl rand -base64 32

Loading Environment Variables

Velox TS uses dotenv for environment variable loading:

// Automatic loading in entry point
import 'dotenv/config';

// Or manual loading
import dotenv from 'dotenv';
dotenv.config({ path: '.env.production' });

Vite/RSC Applications

For RSC apps with Vite, load dotenv explicitly:

import dotenv from 'dotenv';
import { dirname, resolve } from 'path';
import { fileURLToPath } from 'url';

const __dirname = dirname(fileURLToPath(import.meta.url));
dotenv.config({ path: resolve(__dirname, '..', '.env') });

Validation

Built-in Security Validation

Velox TS provides built-in validation for production deployments:

import { validateSecurityOrThrow } from '@veloxts/velox';

// Validates in production, silent in dev/test
validateSecurityOrThrow();

// Or validate auth secrets specifically
import { validateAuthSecrets } from '@veloxts/velox';
validateAuthSecrets();

This validates:

• Required environment variables are set (DATABASE_URL)
• JWT secrets meet minimum length (32 characters)
• Secrets are not weak patterns (e.g., “password”, “secret”)

See Security Validation for details.

Custom Validation with Zod

For additional validation:

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().min(1),
  JWT_SECRET: z.string().min(32),
  JWT_REFRESH_SECRET: z.string().min(32),
});

const env = envSchema.parse(process.env);

Related Content

• Environment Configuration - Presets and security validation
• Configuration Reference - Full config options
• Troubleshooting - Common issues