Environment variables
What you’ll learn
- What environment variables are, in plain words
- The difference between
.envand.env.example - How Strutvane catches a missing or wrong setting before it causes trouble
What are environment variables?
Section titled “What are environment variables?”Your app needs settings that differ between places. On your laptop it talks to a local database; on the production server it talks to a real one, with a real password.
Writing those settings into your code would be a bad idea: everyone with the code would see your passwords. Instead, they live in environment variables: named settings outside the code, like DB_PASSWORD=secret.
.env vs .env.example
Section titled “.env vs .env.example”.env |
.env.example |
|
|---|---|---|
| What’s in it | Your real settings and secrets | Every setting’s name, with comments and safe example values |
| Committed to Git? | Never | Yes |
| Who uses it | Your app, on your machine | Your teammates, as a checklist of what to set |
Think of .env.example as the form and .env as your filled-in copy. You share the blank form, never your filled-in one.
# ─── Database ─────────────────────────────DB_CONNECTION=postgres # postgres | mysql | sqlite | azure-postgres | azure-mysqlDB_HOST=127.0.0.1DB_PORT=5432DB_DATABASE=acmeDB_USERNAME=acmeDB_PASSWORD= # set your own in .env
# ─── Application ──────────────────────────APP_KEY= # generate with: pnpm sv key:generateAPP_DEBUG=true # never true in productionDB_CONNECTION=postgresDB_HOST=127.0.0.1DB_PORT=5432DB_DATABASE=acmeDB_USERNAME=acmeDB_PASSWORD=my-local-passwordAPP_KEY=base64:3q2+7w8kZ...APP_DEBUG=trueWhen you create a project, Strutvane fills in .env for you and generates the secrets. .gitignore already excludes .env, so you can’t commit it by accident.
Strutvane checks your settings at start-up
Section titled “Strutvane checks your settings at start-up”Every setting is described once, with a schema, in env.schema.ts:
import { z } from 'zod'import { defineEnv } from '@strutvane/core'
export const env = defineEnv(z.object({ DB_PORT: z.coerce.number().int(), APP_KEY: z.string().min(32),}))If a setting is missing or wrong, your app refuses to start and lists every problem at once:
Invalid environment: 2 problem(s) - DB_PORT: Invalid input: expected number, received NaN - APP_KEY: Invalid input: expected string, received undefinedFix: set these keys in your .env file (see .env.example for every key and its meaning), then restart.The message names the keys, but never prints their values, so a secret can’t leak into a log.
That’s much better than the app starting and failing later in a confusing way.
Handy commands
Section titled “Handy commands”| Command | What it does |
|---|---|
pnpm sv key:generate |
Creates a secure APP_KEY in .env |
pnpm sv env:check |
Compares your .env with .env.example and lists missing, unknown, empty and invalid settings, plus any secret committed in .env.example. It never prints values. |
When you add a package
Section titled “When you add a package”Package installers add their settings to both files: real local values in .env, documented blanks in .env.example. Your teammates see the new settings the next time they pull. Secrets get a random value in .env and an empty value in .env.example. (Running them with pnpm sv add <package> works today for packages that ship an installer; the auth and UI installers are Planned.)