better-env_skill

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