Environment Variables

This guide covers how environment variables work in StartupKit and the helpers available for managing them.

Quick Setup

After running npx startupkit init, create your environment file:

cp .env.example .env.local

The .env.example file contains all available variables with documentation.

Environment Files

Core Variables

These variables are used across the application:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp
BETTER_AUTH_SECRET=your-secret-key-here

Generate a secure auth secret:

openssl rand -base64 32

Running with Environment Variables

StartupKit includes helpers for running commands with environment variables loaded:

pnpm with-env

Runs a command with .env.local loaded:

pnpm with-env <command>

Examples:

# Run database migrations with env vars
pnpm with-env pnpm db:migrate

# Run a script with env vars
pnpm with-env node scripts/seed.js

# Start the dev server (already uses with-env internally)
pnpm dev

pnpm with-test-env

Runs a command with .env.test loaded:

pnpm with-test-env <command>

Examples:

# Run tests with test environment
pnpm with-test-env pnpm test

# Run a specific test file
pnpm with-test-env vitest run src/lib/auth.test.ts

This is useful for:

• Using a separate test database
• Mocking external services
• Isolated test configurations

Next.js Environment Rules

Next.js has specific rules for environment variables:

# Exposed to browser - safe for public API keys
NEXT_PUBLIC_POSTHOG_KEY=phc_xxx

# Server only - never exposed to client
DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=xxx

Package-Specific Variables

Each package has its own environment variables documented in its respective section:

• Authentication — OAuth providers, auth settings
• Analytics — PostHog, Google Analytics, OpenPanel
• Database — Connection strings, pooling
• Emails — Resend API keys

Deployment

See the Deployment guide for platform-specific instructions on setting environment variables in production.

Security Best Practices

1. Never commit .env.local — It's in .gitignore by default
2. Use different secrets per environment — Dev, staging, production
3. Rotate secrets regularly — Especially after team changes
4. Limit access — Only give team members access to secrets they need

Troubleshooting

Variable Not Available

1. Check the name matches exactly (case-sensitive)
2. Restart the dev server after changes
3. For client-side, ensure NEXT_PUBLIC_ prefix
4. In Vercel, check the correct environment is selected

"Process is not defined"

This happens when accessing server-only variables on the client. Keep server-only variables in server-only files:

// lib/db.ts (server-only, never imported by client)
const dbUrl = process.env.DATABASE_URL