\n\n# vite-plugin-validate-env\n\nA Vite plugin that validates your environment variables at **build** or **dev time**. This helps you catch misconfigurations early by [failing fast](https://en.wikipedia.org/wiki/Fail-fast). No more broken builds or 10 minutes of debugging just to realize you forgot a variable 🥲\n\n---\n\n## ✅ Features\n\n- Validate environment variables **at build time only**, zero runtime overhead\n- Fully **type-safe**\n- Supports [standard-schema](https://github.com/standard-schema/standard-schema) — works with Zod, Valibot, ArkType, and more\n- Built-in parsing, validation, and transformation\n- Custom rules and error messages\n\n---\n\n## Installation\n\n```sh\npnpm add -D @julr/vite-plugin-validate-env\n```\n\n## Basic Usage\n\nYou can use the plugin with the [built-in validator](https://github.com/poppinss/validator-lite) for simple use cases, or with libraries like Zod for more advanced schemas.\n\n> [!TIP]\n> I would recommend using a dedicated `env.ts` file to keep your Vite config clean and separate from your environment variable definitions. See the [Using a Dedicated `env.ts` Config File](#using-a-dedicated-envts-config-file) section for more details.\n\n### Built-in Validator\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport { Schema, ValidateEnv } from '@julr/vite-plugin-validate-env'\n\nexport default defineConfig({\n plugins: [\n ValidateEnv({\n validator: 'builtin',\n schema: {\n VITE_MY_VAR: Schema.string(),\n },\n }),\n ],\n})\n```\n\n### Standard Schema Validators\n\nIf you want to use Zod or another validator compatible with [standard-schema](https://github.com/standard-schema/standard-schema), pass the `validator` and `schema` manually:\n\n```ts\nimport { defineConfig } from 'vite'\nimport { z } from 'zod'\nimport { ValidateEnv } from '@julr/vite-plugin-validate-env'\n\nexport default defineConfig({\n plugins: [\n ValidateEnv({\n validator: 'standard', // 👈\n schema: {\n VITE_MY_VAR: z.string(),\n },\n }),\n ],\n})\n```\n\n## Built-in Validator Examples\n\n```ts\nValidateEnv({\n VITE_STRING: Schema.string(),\n VITE_NUMBER: Schema.number(),\n VITE_BOOLEAN: Schema.boolean(),\n VITE_ENUM: Schema.enum(['foo', 'bar'] as const),\n\n // Optional\n VITE_OPTIONAL: Schema.boolean.optional(),\n\n // With format and protocol checks\n VITE_API_URL: Schema.string({ format: 'url', protocol: true }),\n\n // With custom error message\n VITE_PORT: Schema.number({ message: 'You must set a port!' }),\n\n // Custom validator + transform function\n VITE_URL_SUFFIXED_WITH_SLASH: (key, value) => {\n if (!value) throw new Error(`Missing ${key}`)\n\n return value.endsWith('/') ? value : `${value}/`\n },\n})\n```\n\n## Using Standard Schema\n\n`standard-schema` provides a common interface for multiple validation libraries.\n\nHere’s how to use it with Zod, Valibot, or ArkType, or any other library that supports it.\n\n```ts\nimport { defineConfig } from '@julr/vite-plugin-validate-env'\nimport { z } from 'zod'\nimport * as v from 'valibot'\nimport { type } from 'arktype'\n\nexport default defineConfig({\n validator: 'standard',\n schema: {\n VITE_ZOD_VAR: z.string(),\n VITE_VALIBOT_VAR: v.string(),\n VITE_ARKTYPE_VAR: type.string(),\n },\n})\n```\n\n## Using a Dedicated `env.ts` Config File\n\nYou can move your env definitions to a separate file like this:\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport { ValidateEnv } from '@julr/vite-plugin-validate-env'\n\nexport default defineConfig({\n plugins: [\n ValidateEnv({\n // Optional: you can specify a custom path for the config file\n configFile: 'config/env',\n }),\n ],\n})\n```\n\n```ts\n// env.ts\nimport { defineConfig, Schema } from '@julr/vite-plugin-validate-env'\n\nexport default defineConfig({\n validator: 'builtin',\n schema: {\n VITE_MY_VAR: Schema.enum(['foo', 'bar'] as const),\n },\n})\n```\n\n## Typing `import.meta.env`\n\nIn order to have a type-safe `import.meta.env`, the ideal is to use the dedicated configuration file `env.ts`.\nOnce this is done, you would only need to add an `vite-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:\n\n```ts\n/// \n\ntype ImportMetaEnvAugmented = import('@julr/vite-plugin-validate-env').ImportMetaEnvAugmented<\n typeof import('../env').default\n>\n\ninterface ViteTypeOptions {\n // Avoid adding an index type to `ImportMetaDev` so\n // there's an error when accessing unknown properties.\n // ⚠️ This option requires Vite 6.3.x or higher\n strictImportMetaEnv: unknown\n}\n\ninterface ImportMetaEnv extends ImportMetaEnvAugmented {\n // Now import.meta.env is totally type-safe and based on your `env.ts` schema definition\n // You can also add custom variables that are not defined in your schema\n}\n```\n\n## Validation without Vite\n\nIn some cases, you might want to validate environment variables outside of Vite and reuse the same schema. You can do so by using the `loadAndValidateEnv` function directly. This function will validate and also load the environment variables inside the `process.env` object.\n\n> [!WARNING]\n> `process.env` only accept string values, so don't be surprised if a `number` or `boolean` variable comes back as a string when accessing it after validation.\n\n```ts\nimport { loadAndValidateEnv } from '@julr/vite-plugin-validate-env'\n\nconst env = await loadAndValidateEnv(\n {\n mode: 'development', // required\n root: import.meta.dirname, // optional\n },\n {\n // Plugin options. Also optional if you\n // are using a dedicated `env.ts` file\n validator: 'builtin',\n schema: { VITE_MY_VAR: Schema.string() },\n },\n)\n\nconsole.log(env.VITE_MY_VAR)\nconsole.log(process.env.VITE_MY_VAR)\n```\n\n## 💖 Sponsors\n\nIf you find this useful, consider [sponsoring me](https://github.com/sponsors/Julien-R44)! It helps support and maintain the project 🙏\n\n
![](\"https://user-images.githubusercontent.com/8337858/188329992-e74b3393-5bec-48b3-bba9-a8c45d279866.png\")
\n![](\"https://github.com/julien-r44/static/blob/main/sponsorkit/sponsors.png?raw=true\")
\n