vite-plugin-environment

vite-plugin-environment

Expose environment variables to your client code in Vite.js

[plugin]: https://github.com/ElMassimo/vite-plugin-environment
[migration]: https://vite-ruby.netlify.app/guide/migration.html#migrating-to-vite
[vite.js]: http://vitejs.dev/
[EnvironmentPlugin]: https://webpack.js.org/plugins/environment-plugin/
[define]: https://vitejs.dev/config/#define
[Vite Ruby]: https://vite-ruby.netlify.app/config/#source-maps-%F0%9F%97%BA
[meta env]: https://vitejs.dev/guide/env-and-mode.html#env-files
[vite-plugin-env-compatible]: https://github.com/IndexXuan/vite-plugin-env-compatible

Why? 🤔

Although [Vite.js] provides its [own mechanism][meta env] for exposing environment variables through [import.meta.env][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:

``bash
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:

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

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

And then use them as:

`js
const apiKey = process.env.API_KEY
`

$3

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.

`js
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.

$3

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.

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

and then use it as usual:

`js
process.env.VUE_APP_NOT_SECRET_CODE
`

$3

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.

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

and then use it as:

`js
const version = import.meta.env.APP_VERSION
`

$3

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

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

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

Inside the box 📦

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

`js
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.