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 TanStack Start Prisma SaaS Kit installation.

Environment File Structure

Vite loads environment files from apps/web/. Out of the box the kit ships a single committed .env; you add .env.local for secrets:

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

You can optionally add Vite mode files such as .env.development and .env.production (and their .local variants).

Loading order (highest priority last):

1. .env - base configuration
2. .env.local - local overrides and secrets (git-ignored)
3. .env.[mode] - mode-specific overrides (development in pnpm dev, production in vite build)
4. .env.[mode].local - mode-specific local overrides (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

If you create apps/web/.env.development, Vite loads it only in development mode (pnpm dev). Use it for development-specific, non-secret overrides.

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

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 — point at the Docker Postgres (host port 54333)
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)
VITE_SITE_URL="http://localhost:3000"

The Docker compose setup provides a working PostgreSQL instance on host port 54333. Set DATABASE_URL (e.g. in .env.local) to that instance. The Prisma migration command also defaults to this URL when DATABASE_URL is unset.

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
• VITE_ prefix confusion - Only variables prefixed with VITE_ are exposed to client-side code (via import.meta.env); server-only secrets must stay unprefixed and are read from process.env
• Forgetting to restart the dev server - Vite reads environment variables at startup; 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 →