Vite: Assert Environment Variables Exist During Build

A Vite plugin to automatically ensure all environment variables used in your project exist at build time.

It does this in a very simple way by scanning your code for calls to a specified function (default: requireEnv) and checking that all environment variables referenced in those calls are defined in your environment.

It's simple, and it works. Here's an example of it being used in a project.

Features

• Build-time validation: Catches missing environment variables before deployment
• No maintenance overhead: No need to maintain a separate list of required environment variables
• Configurable function name: Customize the function name that triggers environment variable checks
• TypeScript support: Works with JavaScript, TypeScript, JSX, and TSX files

How it works

The plugin scans your code for calls to a specified function (default: requireEnv) and ensures that all environment variables referenced in those calls are defined in your environment.

Installation

pnpm i -D vite-plugin-check-env

Basic Usage

1. Update vite.config.ts:

import { defineConfig } from 'vite'
import { checkEnv } from 'vite-plugin-check-env'

export default defineConfig({
  plugins: [
    checkEnv(),
  ],
})

2. In your code, use the requireEnv function to access environment variables:

// This will be checked at build time
const apiUrl = requireEnv('API_URL')
const secretKey = requireEnv('SECRET_KEY')

3. Make sure your environment variables are defined in your .env file or environment:

API_URL=https://api.example.com
SECRET_KEY=your-secret-key

4. Run your build as usual:

npm run dev
# or
npm run build

If any environment variables are missing, the build will fail with a clear error message.

Configuration

Custom Method Name

You can configure the function name that the plugin looks for:

import { defineConfig } from 'vite'
import { checkEnv } from 'vite-plugin-check-env'

export default defineConfig({
  plugins: [
    checkEnv({
      methodName: 'getEnv' // Look for getEnv() calls instead of requireEnv()
    }),
  ],
})

Then in your code:

const apiUrl = getEnv('API_URL')

Example

Here's a complete example of how to use the plugin:

vite.config.ts

import { defineConfig } from 'vite'
import { checkEnv } from 'vite-plugin-check-env'

export default defineConfig({
  plugins: [
    checkEnv(),
  ],
})

src/config.ts

// These environment variables will be validated at build time
export const config = {
  apiUrl: requireEnv('VITE_API_URL'),
  appName: requireEnv('VITE_APP_NAME'),
  version: requireEnv('VITE_VERSION'),
}

.env

VITE_API_URL=https://api.example.com
VITE_APP_NAME=My App
VITE_VERSION=1.0.0

If you forget to define any of these variables, you'll get a build error like:

Missing environment variables for requireEnv: VITE_VERSION

MIT License