vite-plugin-valibot-env

1.0.2 verified Fri May 01 auth: no javascript

A Vite plugin that validates environment variables against a Valibot schema at build time. Current stable version is 1.0.2, released with support for Vite 8 stable. Released under MIT license. Key differentiators: integrates Valibot's modular and lightweight schema validation, supports optional prefix stripping, value transformation (boolean, integer, float, null), localized error messages via @valibot/i18n, and callback hooks for custom issue handling. Requires Node.js 20+ and Valibot 1.0.0+. Alternative to similar plugins using Zod or Joi, offering tree-shakeable validators.

Common errors

error TypeError: valibot is not a function ↓

cause Using named import `import { valibot } from 'vite-plugin-valibot-env'` instead of default import.

fix

Change to import valibot from 'vite-plugin-valibot-env'.

error Error: Cannot find module 'vite-plugin-valibot-env' ↓

cause Package not installed or not in node_modules.

fix

Run npm install vite-plugin-valibot-env valibot or deno add jsr:@idleberg/vite-plugin-valibot-env valibot.

error The plugin options 'language' require '@valibot/i18n' installed. ↓

cause Missing `@valibot/i18n` peer dependency when using language option.

fix

Install @valibot/i18n with your package manager.

error Error: Valibot schema version mismatch. Expected >=1.0.0 but got 0.x ↓

cause Using an older version of valibot (0.x) with vite-plugin-valibot-env >=0.10.0.

fix

Upgrade valibot to ^1.0.0 and adjust schema syntax.

Warnings

breaking In version 0.10.0, the peer dependency requirement changed from valibot <1.0.0 to >=1.0.0. Valibot 0.x schemas are incompatible. ↓

fix Update Valibot to 1.0.0 or later; adjust schema syntax if needed (Valibot 1.0 breaking changes).

gotcha The default export is the plugin function, not an object with a named export. Attempting `import { valibot }` will result in `undefined`. ↓

fix Use default import: `import valibot from 'vite-plugin-valibot-env'`.

gotcha When using CommonJS require (e.g., in a Node.js environment), you must use `.default` because the package is ESM-first and bundled as CJS with an export default. ↓

fix Use `const valibot = require('vite-plugin-valibot-env').default`.

deprecated The `onBeforeIssues` and `onAfterIssues` callbacks are available but may be removed in future releases in favor of a unified event system. ↓

fix Monitor changelog for migration; currently still supported.

gotcha When using `language` option, you must install `@valibot/i18n` separately and import it in your Vite config. The plugin does not automatically bundle i18n. ↓

fix Install `@valibot/i18n`, then import it in your vite.config file before using the language option.

Install

npm install vite-plugin-valibot-env

yarn add vite-plugin-valibot-env

pnpm add vite-plugin-valibot-env

Imports

valibotEnv (default)

wrong

import { valibot } from 'vite-plugin-valibot-env'

correct

import valibot from 'vite-plugin-valibot-env'

Default export, not named. Use default import.

valibotEnv (require)
wrong
```
const valibot = require('vite-plugin-valibot-env')
```
correct
```
const valibot = require('vite-plugin-valibot-env').default
```
CommonJS require requires `.default` because the package is ESM-first; CJS via bundler fallback.
type Config (TypeScript)
```
import type { Config } from 'vite-plugin-valibot-env'
```
Type import for options object; only available if you need the exact type.

Quickstart

Validates environment variables against a Valibot schema, with value transformation and prefix handling.

import { defineConfig } from 'vite';
import * as v from 'valibot';
import valibotEnv from 'vite-plugin-valibot-env';

const envSchema = v.object({
  VITE_API_URL: v.pipe(v.string(), v.url()),
  VITE_PORT: v.pipe(v.string(), v.transform(Number)),
  VITE_DEBUG: v.optional(v.pipe(v.string(), v.transform((s) => s === 'true'))),
});

export default defineConfig({
  plugins: [
    valibotEnv(envSchema, {
      ignoreEnvPrefix: false,
      transformValues: true,
    }),
  ],
});