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
```
### 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.
```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.
### 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.
```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
```
### 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`.
```js
EnvironmentPlugin({ APP_VERSION: 'local' }, { defineOn: 'import.meta.env' }),
```
and then use it as:
```js
const version = import.meta.env.APP_VERSION
```
### Ignoring `.env` files
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](https://opensource.org/licenses/MIT).