CLI tool for dev-time environment variable validation #642
Description
Summary
This RFC proposes adding a CLI (and possibly IDE) integration for ArkEnv that validates environment variables during development, before build or runtime.
The goal is to make environment variable validation feel like TypeScript: an early guardrail that builds confidence instead of a late runtime check.
Motivation
ArkEnv’s slogan is "Typesafe environment variables from editor to runtime."
This RFC examines where environment variable validation should fit in modern JavaScript workflows.
When we define types with TypeScript, we expect dev-time guarantees. Running tsc gives confidence before any code executes. If typechecking fails, the pipeline stops.
Runtime validators and type systems have a different role. They handle untrusted inputs at runtime, where values must be validated, parsed, and coerced because they are not fully under our control.
Environment variables are somewhere between these two worlds.
In many setups - especially frontend and full-stack apps - environment variables are defined ahead of time in files like .env.development or .env.production. In these cases, developers usually know:
- which variables exist
- their intended types
- their expected values
This creates a dev-time mental model, even though validation often happens at runtime.
Proposal
Add an ArkEnv CLI that checks environment variables (for example, .env files) against an ArkEnv schema at dev time.
Conceptually, it would be similar to:
tscfor TypeScript- existing ArkEnv Vite/Bun plugins
...but it would run earlier in the workflow, without a build or runtime environment.
Possible use cases:
arkenv checkin CI- Pre-commit hooks
- IDE or editor integrations
- Early feedback before starting a dev server
This is not fundamentally new behavior. It mirrors what ArkEnv already does in Vite and Bun plugins, but brings validation closer to the editor.
Goals
- Provide early feedback when environment variables do not match the schema
- Catch misconfigurations before build or runtime
- Strengthen ArkEnv’s "editor to runtime" positioning
- Keep the core library agnostic and lightweight
Non-Goals
- Replacing runtime validation
- Adding environment-specific behavior to ArkEnv core
- Solving secret management or deployment concerns
Open Questions
- Should this be a standalone
arkenvCLI or a subcommand? - How should multiple environments (
.env.development,.env.production, etc.) be handled? - Should this integrate with IDEs directly or via language server hooks?
- How should this interact with existing plugin-based workflows?
Related Work
- Related to
.envlinter #481 (potential overlap or continuation)