vite-plugin-environment

What is vite-plugin-environment?

vite-plugin-environment is a Vite plugin that allows you to inject environment variables into your Vite project. This can be particularly useful for managing different configurations for development, staging, and production environments.

What are vite-plugin-environment's main functionalities?

Basic Environment Variable Injection

This feature allows you to inject basic environment variables into your Vite project. In this example, `NODE_ENV` and `API_URL` are injected into the project.

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

export default defineConfig({
  plugins: [
    EnvironmentPlugin({
      NODE_ENV: 'development',
      API_URL: 'https://api.example.com'
    })
  ]
});

Custom Prefix for Environment Variables

This feature allows you to use a custom prefix for your environment variables. In this example, `MY_APP_API_KEY` is injected with a custom prefix `MY_APP_`.

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

export default defineConfig({
  plugins: [
    EnvironmentPlugin({
      CUSTOM_PREFIX: 'MY_APP_',
      MY_APP_API_KEY: '12345'
    })
  ]
});

Loading Environment Variables from .env Files

This feature allows you to load environment variables from .env files. In this example, all environment variables defined in the .env file are injected into the project.

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

dotenv.config();

export default defineConfig({
  plugins: [
    EnvironmentPlugin(process.env)
  ]
});

Other packages similar to vite-plugin-environment

dotenv

dotenv is a zero-dependency module that loads environment variables from a .env file into process.env. It is widely used in Node.js projects for managing environment variables. Unlike vite-plugin-environment, dotenv does not specifically integrate with Vite and requires additional configuration to work with Vite projects.

vite-plugin-dotenv

vite-plugin-dotenv is another Vite plugin that loads environment variables from .env files. It is similar to vite-plugin-environment but focuses solely on loading variables from .env files without additional features like custom prefixes.

vite-plugin-env-compatible

vite-plugin-env-compatible is a Vite plugin that makes Vite's environment variables compatible with dotenv. It allows you to use dotenv's .env files in a Vite project, similar to vite-plugin-environment, but with a focus on compatibility with existing dotenv setups.

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.

Changelog

1.1.3 (2022-10-19)

Features

• expose types (6b9a73c)