Registry / devops / esbuild-plugin-valibot-env

esbuild-plugin-valibot-env

library0.6.1jsnpmunverified

An esbuild plugin that validates environment variables against a Valibot schema during the build process. Current stable version is 0.6.1 (released 2024). It allows catching misconfigured environment variables early by integrating schema validation into esbuild's plugin system. Key differentiator: uses Valibot's modular and tiny validation library instead of Zod or Joi, making it ideal for frontend builds. Requires esbuild 0.20–0.26 and Valibot ^1.0.0. Supports dotenv files, localized error messages, and optional value transformation.

devops testing

npm install esbuild-plugin-valibot-env

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-VAL

esbuild-plugin-valibot-env

devopsjavascriptv0.6.1

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.

valibotPlugin (default)

✓ import valibotPlugin from 'esbuild-plugin-valibot-env';

✗ const valibotPlugin = require('esbuild-plugin-valibot-env');

Package is ESM-only. Use default import. CommonJS require() will fail unless using dynamic import.

valibotPlugin (named)

✓ import { valibotPlugin } from 'esbuild-plugin-valibot-env';

Named export also exists if you prefer destructuring. Both default and named export the same function.

default export as type

✓ import type ValibotPlugin from 'esbuild-plugin-valibot-env';

✗ import { ValibotPlugin } from 'esbuild-plugin-valibot-env';

TypeScript users: the package ships types. Use 'import type' for the type of the default export; the named export is a const function, not a type.

Shows basic integration: defines a Valibot schema, passes it to the plugin, and runs esbuild build.

import { build } from 'esbuild'; import * as v from 'valibot'; import valibotPlugin from 'esbuild-plugin-valibot-env'; const envSchema = v.object({ MY_API_KEY: v.pipe(v.string(), v.minLength(1)), NODE_ENV: v.union([v.literal('development'), v.literal('production')]), PORT: v.pipe(v.string(), v.regex(/^\d+$/)), }); await build({ entryPoints: ['src/index.ts'], bundle: true, outfile: 'dist/bundle.js', plugins: [ valibotPlugin(envSchema, { envFile: '.env', language: 'en', transformValues: false, }), ], }); console.log('Build succeeded with validated env vars');

Debug

Known issues

breakingPeer dependency valibot >=1.0.0 is required. Version 0.x of valibot is incompatible.

fix

Upgrade valibot to ^1.0.0.

affects: >=0.0.0 <0.6.0

breakingesbuild 0.20 to 0.26 only. Using esbuild <0.20 or >0.26 will cause resolution errors.

fix

Install esbuild version between 0.20 and 0.26 inclusive.

affects: >=0.6.0

gotchaThe plugin does NOT load .env files automatically; you must provide the path via options.envFile (default './.env'). If no file exists, validation will pass with empty variables.

fix

Specify a valid .env file path or ensure environment variables are set otherwise.

affects: >=0.0.0

gotchatransformValues option only converts strings: boolean 'true'/'false', integer/float strings, and 'null'. Other types (like objects) remain strings.

fix

Set transformValues: true if you need automatic parsing; otherwise handle type conversions manually in schema.

affects: >=0.6.0

deprecatedThe plugin is still active but the maintainer recommends vite-plugin-valibot-env for Vite projects.

fix

If using Vite, consider using vite-plugin-valibot-env instead.

affects: >=0.6.0

Errors

Common errors & fixes

Error: Cannot find module 'esbuild-plugin-valibot-env'

Missing npm install of the package.

fix

Run: npm install -D esbuild-plugin-valibot-env

Error: The plugin "valibot" must have a "name" property

esbuild's plugin API expects an object with a `name` property. The plugin default export may not satisfy that if misused.

fix

Ensure you are passing the function result directly: plugins: [valibotPlugin(schema)] not plugins: [valibotPlugin]

TypeError: valibot.object is not a function

Using valibot 0.x with incompatible API.

fix

Upgrade valibot to v1: npm install valibot@^1.0.0

Build failed with 1 error: ValidationError: Environment validation failed

One or more environment variables do not satisfy the schema.

fix

Check your .env file or actual environment variables and ensure they match the schema (e.g., correct types, urls, literals).

Upgrade

Version history

0.6.1latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; the plugin hooks into esbuild's build process.

valibotrequiredPeer dependency; used to define and validate the environment schema.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/idleberg/esbuild-plugin-valibot-env ↗

packageesbuild-plugin-valibot-env ↗

homepagehttps://github.com/idleberg/esbuild-plugin-valibot-env#readme ↗