mcpField
B
better-env

better-env

github.com/andrelandgrafDevelopment2351 installsUpdated 20w ago
Repository

About better-env

A skill for managing environment variables in TypeScript projects, with typed configuration modules and separation of server and public values. It also covers CLI-based validation, local file syncing, and hosted environment variable operations.

Key features

  1. 01Define typed configs with configSchema
  2. 02Load and validate env files with Next.js semantics
  3. 03Sync local files with hosted environments
  4. 04Manage remote environment variables
  5. 05Use Vercel, Netlify, Railway, and Cloudflare adapters

Use cases

  1. 01Catch missing variables before startup or builds
  2. 02Organize configuration by application feature
  3. 03Sync local dotenv files with deployment environments
  4. 04Update remote variables in CI automation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/andrelandgraf/fullstackrecipes --skill better-env

After installing, type/better-envin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
cli.md
config-schema.md
config.md
env-validation.md
runtime.md
vercel-adapter.md

Details

From the project README

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.

Choose the command runner to match the repo:

  • Use npx in npm/pnpm-based repos (for example lockfiles like package-lock.json or pnpm-lock.yaml and scripts run via npm/pnpm).
  • Use bunx in Bun-based repos (for example bun.lock and scripts run via bun).
  • Keep commands aligned with the project's existing package manager/runtime conventions; do not mix runners unless the repo already does.

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

Comments

Markdown supported