npm:vite-plugin-environment

README

`vite-plugin-environment`

Expose environment variables to your client code in Vite.js

Why? 🤔

Although Vite.js provides its own mechanism for exposing environment variables through import.meta.env, sometimes it's not possible or desirable to prefix variables with VITE_.

This plugin is a shorthand for exposing environment variables by configuring define.

It provides the same functionality as webpack's EnvironmentPlugin, but for Vite.js.

Installation 💿

Install the package as a development dependency:

npm i -D vite-plugin-environment # yarn add -D vite-plugin-environment

Usage 🚀

You can provide a list of environment variable names to expose to your client code:

import { defineConfig } from 'vite'
import EnvironmentPlugin from 'vite-plugin-environment'

export default defineConfig({
  plugins: [
    EnvironmentPlugin(['API_KEY', 'DEBUG']),
  ],
})

And then use them as:

const apiKey = process.env.API_KEY

Usage with default values

You may instead provide an object which maps keys to their default values.

The default value for a key is only used if the variable is not defined.

EnvironmentPlugin({
  // Uses 'development' if the NODE_ENV environment variable is not defined.
  NODE_ENV: 'development',

  // Have in mind that variables coming from process.env are always strings.
  DEBUG: 'false',

  // Required: will fail if the API_KEY environment variable is not provided.
  API_KEY: undefined, 
 
  // Optional: will not fail if the APP_VERSION environment variable is missing.
  APP_VERSION: null,
}),

Use null for optional variables, or undefined for variables that must be provided.

Configuration ⚙️

Have in mind that you can add the plugin several times—passing different options to load different sets of variables.

Loading prefixed variables

In some cases, it's useful to load all environment variables with a certain prefix.

You can achieve that by passing 'all' and providing the prefix option.

EnvironmentPlugin('all', { prefix: 'VUE_APP_' }),
EnvironmentPlugin('all', { prefix: 'REACT_APP_' }),

and then use it as usual:

process.env.VUE_APP_NOT_SECRET_CODE

Exposing variables differently

When porting apps to Vite or using SSR it can be useful to expose variables in process.env, which is the default.

In other cases, you may use the defineOn option to expose them in a different object, such as import.meta.env.

EnvironmentPlugin({ APP_VERSION: 'local' }, { defineOn: 'import.meta.env' }),

and then use it as:

const version = import.meta.env.APP_VERSION

Ignoring `.env` files

By default the plugin will load .env files using the same strategy as Vite.js.

If you want to ignore .env files and only use values in process.env, you can opt out:

EnvironmentPlugin(['API_KEY'], { loadEnvFiles: false }),

Inside the box 📦

The first example in this README is equivalent to manually configuring:

import { defineConfig } from 'vite'

export default defineConfig({
  define: {
    'process.env.API_KEY': JSON.stringify(process.env.API_KEY),
    'process.env.DEBUG': JSON.stringify(process.env.DEBUG),
  }
})

except it will also use any variables provided by your .env files, and will fail if any of the specified variables is not defined.

Acknowledgements

I created this library only because I wanted something that:

Reused Vite's loadEnv functionality, making the library very light (no dependencies).
Allowed to provide a subset of variables to expose, and their defaults.

The following libraries might be helpful depending on your use case:

vite-plugin-env-compatible: Convenient if you are porting a Vue CLI or create-react-app.

License

This library is available as open source under the terms of the MIT License.

Usage no npm install needed!