runtime-env-vite-plugin

This skill ensures that environment variables are handled correctly in Vite projects by distinguishing between build-time (static) variables and runtime (dynamic) variables. It enforces a sequential workflow to ensure proper analysis and clean implementation.

When to apply

You MUST apply this skill when:

• Setting up a new Vite project that requires environment variables.
• Refactoring an existing Vite project to use runtime environment variables.
• Adding new environment variables to a project already using @runtime-env/vite-plugin.

Execution Sequence

This skill MUST be executed in the following order. Do not skip steps:

1. [01 - Setup](./references/01-setup.md): Infrastructure, installation, and initial configuration.
2. [02 - Discovery](./references/02-discovery.md): Analyzing the codebase to identify variables and their true types (The "Think" phase).
3. [03 - Migration](./references/03-migration.md): Applying the schema and updating the source code (The "Act" phase).

Pattern Guides

• [The String Trap](./references/the-string-trap.md): How to avoid manual parsing and leverage runtimeEnv for type safety.

Core Mandates

• Never assume a variable is a string just because it was one in a legacy file. Always perform discovery.
• Always remove manual parsing logic (parseInt, JSON.parse) during migration.
• Always run npx runtime-env gen-ts after updating the schema.
• Always place the script tag in index.html before the app entry point.

Strict Prohibitions

• NEVER use the default keyword in .runtimeenvschema.json. All environment values must originate from the environment.
• NEVER modify or delete existing .env files. They are read-only sources of truth.
• NEVER add import { runtimeEnv } from ... or similar. runtimeEnv is a global.
• NEVER add redundant gen-ts or gen-js scripts to package.json.