Skip to content
GitHub

You're reading the docs for Strutvane 0.1, which has reached end of life and no longer gets fixes. Read this page for Strutvane 0.2, the current version.

Environment variables

View as Markdownllms.txt

What you’ll learn

  • What environment variables are, in plain words
  • The difference between .env and .env.example
  • How Strutvane catches a missing or wrong setting before it causes trouble

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 .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.

.env.example (committed)
# ─── Database ─────────────────────────────
DB_CONNECTION=postgres # postgres | mysql | sqlite | azure-postgres | azure-mysql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=acme
DB_USERNAME=acme
DB_PASSWORD= # set your own in .env
# ─── Application ──────────────────────────
APP_KEY= # generate with: pnpm sv key:generate
APP_DEBUG=true # never true in production
.env (your machine only, never committed)
DB_CONNECTION=postgres
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=acme
DB_USERNAME=acme
DB_PASSWORD=my-local-password
APP_KEY=base64:3q2+7w8kZ...
APP_DEBUG=true

When 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:

env.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 undefined
Fix: 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.

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.

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.)