vite-plugin-validate-env

A Vite plugin to validate your environment variables using any standard schema library (Zod, Valibot, ArkType, etc.). It uses @standard-schema/spec under the hood to ensure full library-agnostic compatibility.

✨ Features

• 🛡️ Fail-Safe Validation: Validates environment variables at build & dev-time.
• ⚙️ Agnostic: Works with Zod, Valibot, ArkType, or any Standard Schema.
• 🛑 Fails Fast: Enforced pre-resolution execution halts the Vite process immediately with helpful error output.
• 🪶 Zero Configuration: Seamlessly respects your existing Vite envDir and root settings.
• 📝 Ecosystem Binding: Propagates schema defaults and data transformations directly back into import.meta.env.
• 📦 Lightweight: Zero dependencies.

Installation

npm install vite-plugin-validate-env -D
# Ensure you have your favorite schema library installed, e.g. zod
npm install zod

Usage

First create an env schema. You can use any schema library that implements the standard @standard-schema/spec (zod, valibot, ArkType, etc).

File: src/env.ts

import { z } from "zod";

export const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_APP_NAME: z.string().min(1),
  // Advanced transformations are fully supported:
  VITE_PORT: z.coerce.number().default(3000),
  VITE_FEAT_TOGGLES: z.string().transform((val) => JSON.parse(val)),
});

declare global {
  interface ImportMetaEnv extends z.infer<typeof envSchema> {}
  interface ImportMeta {
    readonly env: ImportMetaEnv;
  }
}

Then use it in your vite.config.ts:

import { defineConfig } from "vite";
import { validateEnv } from "vite-plugin-validate-env";
import { envSchema } from "./src/env";

export default defineConfig({
  plugins: [
    validateEnv(envSchema, {
      // Optional: limit extraction to specific prefixes
      // prefix: "VITE_"
    }),
  ],
});

How it works

The plugin hooks directly into Vite's config resolution step. It accurately loads the environment variables for your current mode (respecting Vite's native envDir and root configurations), and validates them against the schema you provide.

If any environment variables are mismatched or missing, the plugin will seamlessly intercept the build or dev server, print clear and pinpointed error paths directly in your console, and halt the Vite process via standard errors so your development experience remains tight and predictable.

Additionally, because we return evaluated values post-schema matching, any transformation values or default inputs automatically cascade down onto import.meta.env. Since values are injected using Vite's define, complex objects or numbers are perfectly supported without mutating process.env.

Gotchas & Behavior

• Validation Prefix: By default, the plugin specifically looks for the VITE_ prefix (or whatever your Vite envPrefix configuration is set to) and applies schema matching exclusively to those bounds. If you want to expand schema validation to capture all OS-level environment factors, you must explicitly declare { prefix: "" } in the plugin options.

License

MIT