{"id":27517,"library":"vite-plugin-env-schema","title":"vite-plugin-env-schema","description":"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.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/dawsonbooth/vite-plugin-env-schema","tags":["javascript","vite","plugin","environment","validation","schema","env","standard-schema","zod","typescript"],"install":[{"cmd":"npm install vite-plugin-env-schema","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-env-schema","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-env-schema","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin hooks into Vite build pipeline","package":"vite","optional":false},{"reason":"Required for Standard Schema V1 compliance; handles schema validation","package":"@standard-schema/spec","optional":false}],"imports":[{"note":"Default export only; named export not available. ESM-first package.","wrong":"import { envPlugin } from 'vite-plugin-env-schema'","symbol":"default","correct":"import envPlugin from 'vite-plugin-env-schema'"},{"note":"Virtual module `virtual:env` provides a default export. Must be declared in a .d.ts file for TypeScript type inference.","wrong":"import { env } from 'virtual:env'","symbol":"env (virtual module)","correct":"import env from 'virtual:env'"},{"note":"Options type is exported as `EnvSchemaOptions` but typically inferred. Use `envPlugin<typeof envSchema>(envSchema)` for typed validation.","wrong":"import { EnvSchemaOptions } from 'vite-plugin-env-schema'","symbol":"envPlugin type (TypeScript)","correct":"import envPlugin from 'vite-plugin-env-schema'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite'\nimport envPlugin from 'vite-plugin-env-schema'\nimport { z } from 'zod'\n\nconst envSchema = z.object({\n  VITE_API_URL: z.string().url(),\n  VITE_DEBUG: z.boolean().default(false),\n  VITE_PORT: z.coerce.number().int().positive().default(3000),\n})\n\nexport default defineConfig({\n  plugins: [envPlugin(envSchema, { validateOn: 'config' })],\n})\n\n// env.d.ts (for TypeScript clients)\ndeclare module 'virtual:env' {\n  import type { z } from 'zod'\n  import type envSchema from './vite.config'\n  const env: z.infer<typeof envSchema>\n  export default env\n}\n\n// src/main.ts\nimport env from 'virtual:env'\nconsole.log(env.VITE_API_URL) // https://example.com\nconsole.log(env.VITE_DEBUG)    // false (default)\n","lang":"typescript","description":"Basic validation with Zod: creates env schema, injects validated vars, demonstrates TypeScript declaration for type-safe access."},"warnings":[{"fix":"If you relied on 'load' behavior, set validateOn: 'load' explicitly in plugin options.","message":"Default validateOn changed from 'load' to 'config' between v0.x and v1.0.0.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use conditional requires or mock the module in test environments (e.g., vitest config with resolve.alias).","message":"The virtual module 'virtual:env' is resolved at build time only; tests or runtime code outside Vite will throw 'Cannot find module'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use z.coerce for number/boolean defaults, or validate transformed values after string parsing.","message":"Schema 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()).","severity":"gotcha","affected_versions":">=1.0.2"},{"fix":"Update to latest version; custom validation should implement Standard Schema V1.","message":"The package switched from deepmerge to @standard-schema/spec in v1.0.1; any custom validation logic relying on deepmerge is now unsupported.","severity":"deprecated","affected_versions":"<1.0.1"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Create an env.d.ts file in your project root declaring module 'virtual:env' with the correct type inference.","cause":"Missing TypeScript declaration file for the virtual module.","error":"Cannot find module 'virtual:env' or its corresponding type declarations."},{"fix":"Ensure the variable is present in your .env file and, if using Vite's default env prefix, it starts with VITE_.","cause":"Environment variable not defined in .env file or not prefixed with VITE_ and exposed.","error":"Error: Invalid environment variables: \n- VITE_API_URL: Expected string, received undefined"},{"fix":"Use z.coerce.boolean() for env vars that are strings 'true'/'false' or ensure the default matches the string representation.","cause":"Schema default value type mismatch due to missing coercion or incorrect schema shape.","error":"Type 'boolean' is not assignable to type 'never' when using z.boolean().default(false)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}