home / skills / andrelandgraf / fullstackrecipes / better-env

better-env skill

safe

This skill helps you manage typed environment variables across local and remote providers with safe config schemas, validation, and CLI-driven sync.

npx playbooks add skill andrelandgraf/fullstackrecipes --skill better-env

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

2.9 KB

---
name: better-env
description: Better environment variable management for agents and humans with full type safety, CLI-based remote environment synchronization, and environment validation. Use when setting up typed config schemas, validating env variables, or managing remote env vars across Vercel, Netlify, Railway, Cloudflare, and Fly.io with better-env.
---

## Work With better-env In A Repo

## Type-safe environment config modules

Follow this best practice to manage environment variables in TypeScript applications with full type safety and clear server/public boundaries.

`better-env` exports `configSchema` to define typed env modules and recommends placing them in feature-level `config.ts` files (for example `src/lib/auth/config.ts` and `src/lib/database/config.ts`).

Learn more:

- `references/config-schema.md`

## Validate existence of all env variables in the current environment

Run env validation early so missing or invalid values fail fast before `dev`, `build`, or deploy steps.

`better-env validate --environment <name>` loads `.env*` files with Next.js semantics, discovers `src/lib/*/config.ts` modules, and checks every declared variable from your `configSchema` modules.

If your dotenv files intentionally include keys that are not referenced by config modules, add per-env suppressions in `better-env.ts`:

`environments.<env>.ignoreUnused: string[]`

These suppress only the selected local environment during `validate`.
Adapter defaults are merged in automatically; for Vercel,
`VERCEL_OIDC_TOKEN` is ignored by default in `development`, `preview`, and `production`.

Learn more:

- `references/env-validation.md`

## Configure runtime syncing between local files and hosted providers

Use runtime configuration to keep local dotenv targets aligned with provider environments while preserving safe defaults.

Create `better-env.ts` with `defineBetterEnv(...)` and an adapter (`vercelAdapter`, `netlifyAdapter`, `railwayAdapter`, or `cloudflareAdapter`), then define environment mappings, env-file targets, and gitignore behavior.

Learn more:

- `references/config.md`
- `references/runtime.md`

## Use the CLI for day-to-day environment operations

The CLI gives a consistent workflow for initialization, sync, validation, and remote variable management, which is great for local development and CI automation.

Recommended flow in a repo:

1. Run `better-env init` once to verify adapter prerequisites.
2. Run `better-env pull --environment <name>` to sync local env files.
3. Run `better-env validate --environment <name>` before app startup/build.
4. Use `add`, `upsert`, `update`, `delete`, and `load` for remote env changes.

Choose command behavior intentionally:

- `upsert` for idempotent automation and scripts
- `add` when duplicate keys should fail
- `update` when missing keys should fail
- `delete` to remove remote keys
- `load` for batch updates from dotenv files

Learn more:

- `references/cli.md`
- `references/vercel-adapter.md`

Overview

This skill provides better environment variable management with full TypeScript type safety, CLI-driven workflows, and remote synchronization across major hosting providers. It enforces schema-based validation, separates server/public boundaries, and automates syncing between local dotenv files and provider dashboards. Use it to prevent runtime surprises and keep local and remote environments consistent.

How this skill works

Define typed config schemas in feature-level modules (for example src/lib/auth/config.ts) using the exported configSchema. The CLI inspects those modules, loads dotenv files with Next.js semantics, and validates declared variables early. A runtime configuration file (better-env.ts) declares adapters and mappings so the CLI can push, pull, or synchronize variables with Vercel, Netlify, Railway, Cloudflare, and Fly.io.

When to use it

When you need compile-time type safety for environment variables in TypeScript apps
Before dev, build, or deploy to fail fast on missing/invalid env values
When syncing local dotenv files with remote provider environment dashboards
In CI to validate or load production-like envs during automated workflows
When managing distinct environments (development, preview, production) with consistent rules

Best practices

Place typed config modules at feature level (e.g., src/lib/<feature>/config.ts) to keep scope clear
Run better-env validate --environment <name> early in your startup or CI pipeline to catch issues fast
Use upsert for idempotent automation, add when duplicates must fail, and update when missing keys should fail
Declare per-environment ignoreUnused entries to suppress intentionally unused dotenv keys
Keep better-env.ts under source control but avoid committing sensitive env files; use gitignore mappings in the runtime config

Example use cases

Initialize a project with better-env init and verify provider adapters before first deploy
Pull remote variables into .env.local for local testing with better-env pull --environment development
Validate that all declared configSchema keys exist in CI before builds using better-env validate --environment production
Batch load variables from a dotenv file into a provider using better-env load for repeatable deployments
Use upsert in automation to maintain remote envs idempotently across environments

FAQ

How do I ignore unused keys in dotenv files?

Add environment-specific suppressions in better-env.ts using environments.<env>.ignoreUnused: string[] to skip unused keys for that environment.

Which command should I use for automation?

Prefer upsert for idempotent automation. Use add when you want duplicates to fail and update when missing keys must cause an error.