https://github.com/idleberg/vite-plugin-valibot-env

A Vite plugin to validate environment variables against a Valibot schema
https://github.com/idleberg/vite-plugin-valibot-env

environment-variables valibot validation vite-plugin

Last synced: about 2 months ago
JSON representation

A Vite plugin to validate environment variables against a Valibot schema

• Host: GitHub
• URL: https://github.com/idleberg/vite-plugin-valibot-env
• Owner: idleberg
• License: mit
• Created: 2024-04-24T21:33:22.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2025-03-31T19:04:49.000Z (8 months ago)
• Last Synced: 2025-04-23T21:43:21.998Z (7 months ago)
• Topics: environment-variables, valibot, validation, vite-plugin
• Language: TypeScript
• Homepage: https://www.npmjs.com/package/vite-plugin-valibot-env
• Size: 969 KB
• Stars: 4
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

• awesome-vite - vite-plugin-valibot-env - Validate environment variables against a Valibot schema. (Plugins / Framework-agnostic Plugins)
• fucking-awesome-vite - vite-plugin-valibot-env - Validate environment variables against a Valibot schema. (Plugins / Framework-agnostic Plugins)

README

          
# vite-plugin-valibot-env

> A Vite plugin to validate environment variables against a Valibot schema.

[![License](https://img.shields.io/github/license/idleberg/vite-plugin-valibot-env?color=blue&style=for-the-badge)](https://github.com/idleberg/vite-plugin-valibot-env/blob/main/LICENSE)

[![Version: npm](https://img.shields.io/npm/v/vite-plugin-valibot-env?style=for-the-badge)](https://www.npmjs.org/package/vite-plugin-valibot-env)

[![Version: jsr](https://img.shields.io/jsr/v/@idleberg/vite-plugin-valibot-env?style=for-the-badge)](https://jsr.io/@idleberg/vite-plugin-valibot-env)

[![CI: Node](https://img.shields.io/github/actions/workflow/status/idleberg/vite-plugin-valibot-env/node.yml?logo=nodedotjs&logoColor=white&style=for-the-badge)](https://github.com/idleberg/vite-plugin-valibot-env/actions/workflows/node.yml)

[![CI: Deno](https://img.shields.io/github/actions/workflow/status/idleberg/vite-plugin-valibot-env/deno.yml?logo=deno&logoColor=white&style=for-the-badge)](https://github.com/idleberg/vite-plugin-valibot-env/actions/workflows/deno.yml)

## Why? 🤔

It's generally a good idea to check that you're all set up early in the development process. Validating that your environment variables have been defined and are of the expected type is a part of that – for yourself and your colleagues. While there are _many_ libraries to validate against a schema, [Valibot](https://valibot.dev/) stands out for its versatility and modularity. The small footprint already makes it an ideal candidate for validation in the frontend. So why not use it in your development process as well?

## Installation 💿

On NodeJS or Bun you can install from npm

```shell

npm install vite-plugin-valibot-env valibot

```

On Deno you can install using JSR

```shell

deno add jsr:@idleberg/vite-plugin-valibot-env valibot

```

## Usage 🚀

Let's start with a very basic example

```javascript

import { defineConfig } from "vite";

import * as v from "valibot";

import valibot from "vite-plugin-valibot-env";

const schema = v.object({

	VITE_API_ENDPOINT: v.pipe(v.string(), v.url()),

	VITE_LOCALE: v.literal("en_US"),

});

export default defineConfig({

	plugins: [valibot(schema)],

});

```

### API ⚙️

`valibot(schema, options?)`

### Options

#### `options.ignoreEnvPrefix`

Type: `boolean`  

Default: `false`

Setting this to `true` will also validate unprefixed environment variables.

> [!TIP]

> Vite uses a [prefix](https://vitejs.dev/config/shared-options.html#envprefix) to prevent leaking all environment variables into your code. The same limitation applies to the validator. However, there might be use cases where you want validate unprefixed environment variables as well, e.g. `HOST` and `PORT` to configure the Vite server.

#### `options.transformValues`

Type: `boolean`  

Default: `false`

Setting this to `true` will try and transform certain string values to their respective types. Supports booleans, integers, floats, and `null`.

#### `options.language`

Type: `string`  

Default: `undefined`

Language ID for localized error messages.

> [!NOTE]

> When using this option, you need to install `@valibot/i18n` and import it into your Vite config.

#### `options.onBeforeIssues`

Type: `function`  

Default: `undefined`

A callback function executed before any issues have been printed.

#### `options.onAfterIssues`

Type: `function`  

Default: `undefined`

A callback function executed after all issues have been printed.

> [!TIP]

> This can be useful to point collaborators to the documentation of your project's environment variables.

#### `options.throwError`

Type: `boolean`  

Default: `false`

> [!CAUTION]

> This option exists for testing purposes and is not recommended for other use.

Throws an error rather than exiting gracefully when issues have been found in the schema.

## Related 👫

- [esbuild-plugin-valibot-env](https://github.com/idleberg/esbuild-plugin-valibot-env)

## License ©️

This work is licensed under [The MIT License](LICENSE).