Registry / serialization / vite-plugin-env-schema

vite-plugin-env-schema

library1.0.2jsnpmunverified

A Vite plugin (v1.0.2) for build-time validation and injection of environment variables using schema libraries like Zod, Valibot, ArkType, and Effect Schema via the Standard Schema V1 spec. It validates .env values against a defined schema early in the Vite config resolution (or on module load) and exposes them through a virtual module `virtual:env`. Key differentiators from other env plugins (e.g., @julr/vite-plugin-validate-env) include full compatibility with any Standard Schema library and zero runtime dependencies beyond the schema library. Released in July 2025 with an active maintenance cadence.

serialization devops

npm install vite-plugin-env-schema

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-ENV-SC

vite-plugin-env-schema

serializationjavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import envPlugin from 'vite-plugin-env-schema'

✗ import { envPlugin } from 'vite-plugin-env-schema'

Default export only; named export not available. ESM-first package.

env (virtual module)

✓ import env from 'virtual:env'

✗ import { env } from 'virtual:env'

Virtual module `virtual:env` provides a default export. Must be declared in a .d.ts file for TypeScript type inference.

envPlugin type (TypeScript)

✓ import envPlugin from 'vite-plugin-env-schema'

✗ import { EnvSchemaOptions } from 'vite-plugin-env-schema'

Options type is exported as `EnvSchemaOptions` but typically inferred. Use `envPlugin<typeof envSchema>(envSchema)` for typed validation.

Basic validation with Zod: creates env schema, injects validated vars, demonstrates TypeScript declaration for type-safe access.

// vite.config.ts import { defineConfig } from 'vite' import envPlugin from 'vite-plugin-env-schema' import { z } from 'zod' const envSchema = z.object({ VITE_API_URL: z.string().url(), VITE_DEBUG: z.boolean().default(false), VITE_PORT: z.coerce.number().int().positive().default(3000), }) export default defineConfig({ plugins: [envPlugin(envSchema, { validateOn: 'config' })], }) // env.d.ts (for TypeScript clients) declare module 'virtual:env' { import type { z } from 'zod' import type envSchema from './vite.config' const env: z.infer<typeof envSchema> export default env } // src/main.ts import env from 'virtual:env' console.log(env.VITE_API_URL) // https://example.com console.log(env.VITE_DEBUG) // false (default)

Debug

Known issues

breakingDefault validateOn changed from 'load' to 'config' between v0.x and v1.0.0.

fix

If you relied on 'load' behavior, set validateOn: 'load' explicitly in plugin options.

affects: >=1.0.0

gotchaThe virtual module 'virtual:env' is resolved at build time only; tests or runtime code outside Vite will throw 'Cannot find module'.

fix

Use conditional requires or mock the module in test environments (e.g., vitest config with resolve.alias).

affects: >=1.0.0

gotchaSchema must be an object with string-to-string record fields (env vars are always strings initially). Non-string default values (e.g., numbers) require coercion (e.g., z.coerce.number()).

fix

Use z.coerce for number/boolean defaults, or validate transformed values after string parsing.

affects: >=1.0.2

deprecatedThe package switched from deepmerge to @standard-schema/spec in v1.0.1; any custom validation logic relying on deepmerge is now unsupported.

fix

Update to latest version; custom validation should implement Standard Schema V1.

affects: <1.0.1

Errors

Common errors & fixes

Cannot find module 'virtual:env' or its corresponding type declarations.

Missing TypeScript declaration file for the virtual module.

fix

Create an env.d.ts file in your project root declaring module 'virtual:env' with the correct type inference.

Error: Invalid environment variables: - VITE_API_URL: Expected string, received undefined

Environment variable not defined in .env file or not prefixed with VITE_ and exposed.

fix

Ensure the variable is present in your .env file and, if using Vite's default env prefix, it starts with VITE_.

Type 'boolean' is not assignable to type 'never' when using z.boolean().default(false)

Schema default value type mismatch due to missing coercion or incorrect schema shape.

fix

Use z.coerce.boolean() for env vars that are strings 'true'/'false' or ensure the default matches the string representation.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

viterequiredPeer dependency; plugin hooks into Vite build pipeline

@standard-schema/specrequiredRequired for Standard Schema V1 compliance; handles schema validation

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dawsonbooth/vite-plugin-env-schema ↗

packagehttps://www.npmjs.com/package/vite-plugin-env-schema ↗