Env management

Warnings

• Make sure to have the git hook setup OR TO add any new variable viw the dedicated subcommand
• Obviously do not commit your password file
• In variable composition, the "static" parts are NOT encrypted (static part should never contain sensitive information)

Goals

• Centralize env variables definitions
• Allow explicit variables composition
• Good DX (setup and forget)

TODOs

• [x] Handle encryption
• [ ] Fix not scoped package detection (if one package is not scope, it fails with pkg.name something)
• [ ] Handle variable composition everywhere (not just in overrides)
• [x] Create runtime library to read vars (even encrypted)
• [x] Handle env.local files

Open questions

• Should we write all the env with the next.js convention ?
• How to handle adding a var easily in an encrypted context ?
• Should we split BUILD / RUN variables ?

Examples

in package.json (root)

{
	"scripts": {
		"postinstall": "wrenv --secret ~/.big-secret write --target dev",
		"env:update": "wrenv --secret ~/.big-secret write"
	}
}

and then later

pnpm run env:update --target prod

or

WRENV_TARGET=staging bun run env:update

Writing all environments

Use --target all to write environment files for all configured environments at once. This creates suffixed files using conventional names (.env.development, .env.staging, .env.production) instead of a single .env file.

Internal names are mapped to conventional output names:

• dev → .env.development
• preprod → .env.staging
• production → .env.production

wrenv --secret ~/.big-secret write --target all

This is useful for:

• CI/CD pipelines that need all environment configurations
• Docker builds that copy environment-specific files
• Pre-generating all env files for deployment
• Compatibility with Next.js, Vite, and other frameworks that use conventional env file names

you can also pass the secret via an env variable (Even though it is not really encouraged)

WRENV_SECRET=super-secret WRENV_TARGET=prod npm run env:update

or via stdin

cat ~/.big-secret | wrenv --secret=stdin write --target=dev
wrenv --secret stdin --target=dev < ~/.big-secret

Git hooks

Wrenv provide a git hook (to be configured independently with the solution of your choosing) to encrypt all added variables So in .git/hooks/pre-commit you can add

bun run wrenv --secret ~/.big-secret besafe

This will run on the .env.json file and make sure all variables are encrypted. This way you can add new variables and make sure they don't leak, offering minimum friction.

/!\ You must make sure to add this hook OR to always add var via the dedicated subcommand wrenv add

Add a variable

To add a new variable use the add subcommand

wrenv --secret=~/.big-secret add NEW_VAR +fallback=@@_VALUE +dev=DEV_VALUE +production=PROD_VALUE