vite-plugin-browser-env

English | 简体中文

A Vite plugin that safely injects environment variables from .env files into the browser runtime, allowing for easy modification of environment variables at runtime, One-pack multi-environment deployment.

Features

Injects specified environment variables into the window.env object in the browser
Supports custom environment variable prefixes, object names, and file names
Allows including and excluding specific environment variables
Automatically generates a JavaScript version of the environment variable configuration file in the dist root directory for easy runtime modification

Installation

Using npm:

npm install vite-plugin-browser-env -D

Or using yarn or pnpm:

yarn add vite-plugin-browser-env -D
pnpm add vite-plugin-browser-env -D

Usage

Import and use the plugin in your vite.config.ts file:

import { defineConfig } from 'vite';
import browserEnvPlugin from 'vite-plugin-browser-env';

export default defineConfig({
  plugins: [
    browserEnvPlugin({
      // Configuration options
    }),
  ],
});

Options

Option	Type	Default	Description
`prefix`	`string`	`'VITE_'`	Environment variable prefix
`envObjectName`	`string`	`'env'`	Property name injected into the `window` object
`fileName`	`string`	`'env-config.js'`	Generated environment configuration file name
`includes`	`string[]`	`[]`	List of environment variables to always include
`excludes`	`string[]`	`[]`	List of environment variables to always exclude

Example

Assuming your .env file contains:

VITE_APP_API_PROXY = http://api.example.com
VITE_APP_API_BASE = /api/
VITE_APP_FILE_BASE = /file-server/
VITE_APP_FILE_BUCKET = example-bucket
VITE_APP_SECRET = 123456

And your vite.config.ts is configured as:

import { defineConfig } from 'vite';
import browserEnvPlugin from 'vite-plugin-browser-env';

export default defineConfig({
  plugins: [
    browserEnvPlugin({
      prefix: 'VITE_',
      includes: ['NODE_ENV'],
      excludes: ['VITE_APP_SECRET', 'VITE_APP_FILE_BUCKET'],
      envObjectName: 'env',
      fileName: 'env-config.js',
    }),
  ],
});

This configuration will:

Include environment variables starting with VITE_
Include the NODE_ENV environment variable
Exclude VITE_APP_SECRET and VITE_APP_FILE_BUCKET environment variables
Inject matching environment variables into the window.env object
Generate a configuration file named env-config.js in the dist root directory

The generated env-config.js file will contain:

window.env = {
  VITE_APP_API_PROXY: 'http://api.example.com',
  VITE_APP_API_BASE: '/api/',
  VITE_APP_FILE_BASE: 'http://file.example.com/',
  NODE_ENV: 'development',
};

You can access the injected environment variables through the window.env object in the browser console:

console.log(window.env.VITE_APP_API_PROXY); // Output: http://api.example.com

To easily modify environment variables after deployment, use window.env instead of import.meta.env in your code:

import axios from 'axios';

// Create axios instance
const http = axios.create({
  // baseURL: import.meta.env.VITE_APP_API_BASE,
  baseURL: window.env.VITE_APP_API_BASE, // Use window.env instead of import.meta.env
});

Notes

Ensure that sensitive information (such as keys and passwords) is not exposed to the frontend through this plugin.
In production environments, it's recommended to expose only necessary environment variables.

Contributing

Issues and pull requests are welcome. For major changes, please open an issue first to discuss the proposed changes.

License

MIT