Environment Variables Configuration

For local development, the kit works out of the box with the provided .env and .env.development files. Store any secrets (API keys, passwords) in .env.local, which is git-ignored. See the complete environment variables reference for all available options.

This guide is part of the Next.js Drizzle SaaS Kit installation.

Environment File Structure

The kit uses multiple environment files:

apps/web/
├── .env                   # Shared, public variables (committed to git)
├── .env.development       # Development-specific variables
├── .env.local             # Local secrets (NEVER commit - git-ignored)

Loading order:

1. .env - Base configuration (loaded first)
2. .env.development - Development-specific overrides
3. .env.local - Local overrides and secrets (highest priority, git-ignored)

Base Environment Variables

The file apps/web/.env is a shared environment file that contains all the base environment variables required for running the application. It is committed to git and is therefore public.

This file should not contain any sensitive information - please make sure to add any sensitive information to the .env.local file.

Development Environment Variables

The file apps/web/.env.development contains all the variables required for running the development environment locally.

If you add secret information to this file, please make sure it's only testing information - you don't want to commit any sensitive information to this file.

Local Environment Variables

The file apps/web/.env.local is never committed to git and can be used to store any sensitive information that you don't want to commit to the repository for making the variables available only to your local environment.

Where to store sensitive information?

While developing your application, you can store sensitive information in the .env.local file. When you deploy your application to production, you should use your hosting platform's environment variables to store sensitive information.

Minimum Required Variables

For local development with Docker, these variables are pre-configured. For production or custom setups, you need:

# Database connection (provided by Docker compose for local dev)
DATABASE_URL="postgresql://postgres:postgres@localhost:54333/postgres"
# Authentication secret (generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET="your-32-character-minimum-secret-here"
# Site URL (change for production)
NEXT_PUBLIC_SITE_URL="http://localhost:3000"

The Docker compose setup provides a working PostgreSQL instance, so you don't need to configure DATABASE_URL for local development.

Common Pitfalls

• Putting secrets in .env instead of .env.local - The .env file is committed to git; never put API keys or passwords there
• Missing BETTER_AUTH_SECRET - Authentication will fail silently without this; generate a secure 32+ character string
• Incorrect DATABASE_URL format - Must be a valid PostgreSQL connection string; check for typos in host, port, or credentials
• NEXT_PUBLIC_ prefix confusion - Only variables prefixed with NEXT_PUBLIC_ are available in client-side code; server-only secrets should never have this prefix
• Forgetting to restart the dev server - Environment variable changes may require restarting pnpm dev to take effect; check the terminal for any errors or warnings

Next Steps

For a complete list of all environment variables including authentication, billing, email, and storage configuration, see the Environment Variables Reference.

Next: Running the Project →