Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Julien-R44/vite-plugin-validate-env
✅ Vite plugin for validating your environment variables
https://github.com/Julien-R44/vite-plugin-validate-env
env-vars validation vite-plugin
Last synced: 3 months ago
JSON representation
✅ Vite plugin for validating your environment variables
- Host: GitHub
- URL: https://github.com/Julien-R44/vite-plugin-validate-env
- Owner: Julien-R44
- License: mit
- Created: 2022-09-04T01:27:15.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-03T06:47:15.000Z (9 months ago)
- Last Synced: 2024-10-18T00:24:36.765Z (3 months ago)
- Topics: env-vars, validation, vite-plugin
- Language: TypeScript
- Homepage:
- Size: 313 KB
- Stars: 167
- Watchers: 2
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
- fucking-awesome-vite - vite-plugin-validate-env - Validate your environment variables at build time. Never forget an environment variable again. (Plugins / Framework-agnostic Plugins)
- awesome-vite - vite-plugin-validate-env - Validate your environment variables at build time. Never forget an environment variable again. (Plugins / Framework-agnostic Plugins)
README
This Vite plugin allows you to validate your environment variables at build or dev time. This allows your build/dev-server to [fail-fast](https://en.wikipedia.org/wiki/Fail-fast) if your setup is misconfigured.
No more CI to restart because you are missing an environment variable, or to realize after 10 minutes of debugging that you forgot a variable 🥲
## Features
- Validate your environment variables at **build time only**. No runtime overhead
- Totally type-safe
- Support multiple validation librairies ( [Zod](https://zod.dev/), and [@poppinss/validator-lite](https://github.com/poppinss/validator-lite/) )
- Parsing, validation and transformation of your variables
- Custom rules and error messages## Installation
```sh
pnpm add -D @julr/vite-plugin-validate-env
```## Usage
`vite-plugin-validate-env` plugin allows you to validate your env, either with a very simplified builtin validation lib, or with Zod in the most complex cases when you want a very strict validation.### Plugin options
The easiest way to define the options is to directly define the scheme as follows:
```ts
// vite.config.ts
import { defineConfig } from "vite";
import { Schema, ValidateEnv } from "@julr/vite-plugin-validate-env";export default defineConfig({
plugins: [
ValidateEnv({
VITE_MY_VAR: Schema.string()
}),
],
})
```In case you want to change some plugin options, in particular change the validator (for Zod), you have to set your options as follows:
```ts
import { defineConfig } from "vite";
import { z } from 'zod'
import { ValidateEnv } from "@julr/vite-plugin-validate-env";export default defineConfig({
plugins: [
ValidateEnv({
validator: 'zod',
schema: {
VITE_MY_VAR: z.string()
}
}),
],
})
```If you want to see what values are being evaluated for the build, for example when running in CI. You can pass the `debug` option as follows:
```ts
import { defineConfig } from "vite";
import { Schema, ValidateEnv } from "@julr/vite-plugin-validate-env";export default defineConfig({
plugins: [
ValidateEnv({
debug: true,
schema: {
VITE_MY_VAR: Schema.string()
}
}),
],
})
```### Built-in validator
```ts
import { Schema, ValidateEnv } from "@julr/vite-plugin-validate-env"
import { defineConfig } from "vite";export default defineConfig({
plugins: [
ValidateEnv({
// Data types
VITE_STRING_VARIABLE: Schema.string(),
VITE_BOOLEAN_VARIABLE: Schema.boolean(),
VITE_NUMBER_VARIABLE: Schema.number(),
VITE_ENUM_VARIABLE: Schema.enum(['foo', 'bar'] as const),
// Optional variable
VITE_OPTIONAL_VARIABLE: Schema.boolean.optional(),// Specify string format
VITE_AUTH_API_URL: Schema.string({ format: 'url', protocol: true }),// Specify error message
VITE_APP_PORT: Schema.number({ message: 'You must set a port !' }),// Custom validator
VITE_CUSTOM_VARIABLE: (key, value) => {
if (!value) {
throw new Error(`Missing ${key} env variable`)
}if (value.endsWith('foo')) {
throw new Error('Value cannot end with "foo"')
}return value
},
}),
],
})
```### Zod Validator
To use the Zod validator, you must first install it if you have not already done so
```
pnpm install zod
```Then, you can use it as follows:
```ts
// env.ts
import { defineConfig } from '@julr/vite-plugin-validate-env'
import { z } from 'zod'export default defineConfig({
validator: 'zod',
schema: {
VITE_MY_STRING: z.string().min(5, 'This is too short !'),
VITE_ENUM: z.enum(['a', 'b', 'c']),
VITE_BOOLEAN_VARIABLE: z.boolean(),
}
})
```Beware, there are some limitations if you use Zod. For example, you can't use a boolean or number type directly. Because everything that comes from your `.env` file is a string by default.
So to validate other types than string you must use `preprocess`, and `transform`, like this:
```ts
// env.ts
import { defineConfig } from '@julr/vite-plugin-validate-env'
import { z } from 'zod'export default defineConfig({
validator: 'zod',
schema: {
// This will transform the string 'true' or '1' to a boolean
VITE_BOOLEAN_VARIABLE: z
.preprocess((value) => value === 'true' || value === '1', z.boolean()),// Will convert the string to a number
VITE_NUMBER: z.preprocess((value) => Number(value), z.number()),// Will parse the string to an object
VITE_OBJECT: z.preprocess(
(value) => JSON.parse(value as string),
z.object({
a: z.string(),
b: z.number(),
}),
),
}
})
```In this case, `true` and `1` will be transformed to `true` and your variable will be valid and considered as a boolean.
## Dedicated config file
You can also add a `env.ts` file at the root of your project to define your environment variables.
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { ValidateEnv } from "@julr/vite-plugin-validate-env";export default defineConfig({
plugins: [ValidateEnv()],
})
``````ts
// env.ts
import { defineConfig, Schema } from '@julr/vite-plugin-validate-env'export default defineConfig({
VITE_MY_VAR: Schema.enum(['foo', 'bar'] as const),
})
```### Custom config file path
By default, the plugin is looking for a file named `env.ts` at the root of your project. If you want to use a different file, you can specify the path to your file in the plugin options.
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { ValidateEnv } from "@julr/vite-plugin-validate-env";export default defineConfig({
plugins: [ValidateEnv({ configFile: 'config/env' })],
})
```This will look for a file named `env.ts` in the `config` folder at the root of your project. Make sure to not include the file extension in the path as the plugin will automatically search for `.js`, `.ts` and other valid file extensions.
## Transforming variables
In addition to the validation of your variables, there is also a parsing that is done. This means that you can modify the value of an environment variable before it is injected.Let's imagine the following case: you want to expose a variable `VITE_AUTH_API_URL` in order to use it to call an API. However, you absolutely need a trailing slash at the end of this environment variable. Here's how it can be done :
```ts
// Built-in validation
import { defineConfig, Schema } from '@julr/vite-plugin-validate-env'export default defineConfig({
VITE_AUTH_API_URL: (key, value) => {
if (!value) {
throw new Error(`Missing ${key} env variable`)
}if (!value.endsWith('/')) {
return `${value}/`
}return value
},
})
``````ts
// Zod validation
import { defineConfig } from '@julr/vite-plugin-validate-env'
import { z } from 'zod'export default defineConfig({
validator: 'zod',
schema: {
VITE_AUTH_API_URL: z
.string()
.transform((value) => value.endsWith('/') ? value : `${value}/`),
},
})
```Now, in your client front-end code, when you call `import.meta.env.VITE_AUTH_API_URL`, you can be sure that it will always end with a slash.
## Typing `import.meta.env`
In order to have a type-safe `import.meta.env`, the ideal is to use the dedicated configuration file `env.ts`.
Once this is done, you would only need to add an `env.d.ts` in `src/` folder to augment `ImportMetaEnv` (as [suggested here](https://vitejs.dev/guide/env-and-mode.html#env-files) ) with the following content:```ts
///type ImportMetaEnvAugmented = import('@julr/vite-plugin-validate-env').ImportMetaEnvAugmented<
typeof import('../env').default
>interface ImportMetaEnv extends ImportMetaEnvAugmented {
// Now import.meta.env is totally type-safe and based on your `env.ts` schema definition
// You can also add custom variables that are not defined in your schema
}```
## Sponsors
If you like this project, [please consider supporting it by sponsoring it](https://github.com/sponsors/Julien-R44/). It will help a lot to maintain and improve it. Thanks a lot !
![](https://github.com/julien-r44/static/blob/main/sponsorkit/sponsors.png?raw=true)
## License
[MIT](./LICENSE.md) License © 2022 [Julien Ripouteau](https://github.com/Julien-R44)