runtime-env-vite-plugin

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: Infrastructure, installation, and initial configuration.
2. 02 - Discovery: Analyzing the codebase to identify variables and their true types (The "Think" phase).
3. 03 - Migration: Applying the schema and updating the source code (The "Act" phase).

Pattern Guides

• The String Trap: 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.