diegosouzapw Environment Variables
Patterns for managing and validating environment variables using t3-env with Zod.
Configuration file: src/lib/env.ts
Variable Types
Client Variables (VITE_ prefix)
Variables the browser can read. Must have VITE_ prefix to be exposed to client code.
- Public API endpoints
- Public keys (Stripe publishable key, analytics ID)
- Feature flags for UI
Server Variables (no prefix)
Variables only available on the server. Never exposed to the browser.
- API secrets and private keys
- Database connection strings
- Internal service URLs
Shared Variables
Values derived from the build environment, available in both contexts.
DEV- Whether running in development modeNODE_ENV- Current environment
Vite Exposure Rules
Vite only exposes variables prefixed with VITE_ to client code via import.meta.env. Variables without this prefix are only available server-side.
| Prefix | Client | Server | Example |
|---|---|---|---|
VITE_* |
Yes | Yes | VITE_API_URL |
| No prefix | No | Yes | DATABASE_URL |
Usage
import { env } from "@/lib/env";
console.log("Is dev?", env.DEV);
Environment Files
The project uses two environment files with different purposes:
| File | Purpose | Git |
|---|---|---|
.env |
Development defaults (local URLs, non-sensitive config) | Committed |
.env.local |
Secrets, API keys, overrides | Ignored |
Load order (highest priority first):
.env.local- Overrides, secrets (never committed).env- Development defaults (committed)
This pattern allows:
- Easy onboarding - clone and run with sensible defaults
- Secrets stay out of git
- Production values set in deployment environment
Adding New Variables
- Add to
src/lib/env.tswith Zod validation in appropriate section (client,server, orshared) - If it's a sensible development default (local URL, etc.): add to
.env - If it's a secret or API key: add to
.env.local - Configure in deployment environment
- Add a test in the co-located test file (
src/lib/env.test.ts) verifying the validation accepts correct values and rejects invalid ones.
Quick Reference
| Task | Action |
|---|---|
| Access env var | import { env } from "@/lib/env" |
| Client variable | Add to client with VITE_ prefix |
| Server variable | Add to server (no prefix, never exposed to browser) |
| Shared variable | Add to shared (build-time values) |
| Validation | Use Zod schemas (z.string(), z.boolean(), etc.) |