vite-plugin-runtime
Version:
Vite plugin that enables configuring runtime environment variables when building
229 lines (163 loc) • 4.89 kB
Markdown
# vite-plugin-runtime
[](https://sonarcloud.io/summary/new_code?id=flexbase-eng_vite-plugin-runtime)
[](https://sonarcloud.io/summary/new_code?id=flexbase-eng_vite-plugin-runtime) [](LICENSE)
Inject runtime environment variables and html based on the [vite mode](https://vitejs.dev/guide/env-and-mode.html).
## Installation
```
npm install --save-dev vite-plugin-runtime
```
or
```
yarn add vite-plugin-runtime --dev
```
## runtimeEnv
### Summary
This plugin allows build toolchains to inject variables at compile time instead of relying on multiple `.env.*` environment dotenv files.
This is especially useful for values that need to be managed externally from source code.
This plugin replaces usage of `import.meta.env.VITE_*` with `import.meta.env.*`.
| vite | vite-plugin-runtime |
| ------------------------------ | ------------------------- |
| `import.meta.env.VITE_APP_KEY` | `import.meta.env.APP_KEY` |
---
.env file
| vite | vite-plugin-runtime |
| ------------------------- | -------------------- |
| `VITE_APP_KEY=some value` | `APP_KEY=some value` |
---
During the build this plugin will convert all occurences of `import.meta.env.*` to `window.env.*`
| Code | Runtime |
| ------------------------- | -------------------- |
| `import.meta.env.APP_KEY` | `window.env.APP_KEY` |
### Usage
#### vite.config
The plugin options can be injected in the constructor or as a separate object on the vite config object.
```ts
import { runtimeEnv } from 'vite-plugin-runtime';
export default defineConfig({
plugins: [
runtimeEnv(),
],
runtimeEnv: {}, // optional configuration object
```
### Configuration
#### name
This is the name of the object attached to the `window` instance. Default is `env`.
```ts
name?: (() => string) | string
```
```ts
runtimeEnv({
name: 'customName',
}),
```
outputs `window.customName.*`
#### generateTypes
Specificies whether to generate typescript types for `import.meta.env`. Default is `false`.
```ts
generateTypes?: boolean
```
```ts
runtimeEnv({
generateTypes: true,
}),
```
#### generatedTypesPath
The path to generate typescript types. Only takes affect if [generateTypes](#generatetypes) is `true`. Default is `process.cwd()`
```ts
generatedTypesPath?: (() => string) | string
```
```ts
runtimeEnv({
generatedTypesPath: () => './src',
}),
```
generatedTypesPath combined with [generateTypes](#generatetypes) will create a type definition file `env.d.ts`:
```js
/** generated by vite-plugin-runtime */
interface ImportMetaEnv {
readonly APP_KEY: string;
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}
```
#### injectHtml
Specifies whether to inject an env loading script into `index.html`. Defaults to `true`.
```ts
injectHtml?: boolean
```
```ts
runtimeEnv({
injectHtml: false,
}),
```
When `true` the plugin will inject
```html
<script type="module">
import rtenv from '/env.js';
window.env = { ...window.env, ...rtenv };
</script>
```
into the `index.html` `<head></head>` section.
The generated script will resemble:
```js
export default {
APP_KEY: 'some value',
};
```
#### envsubstTemplate
Specifies whether to create an envsubst template file at build time. Defaults to `false`.
```ts
envsubstTemplate?: boolean
```
```ts
runtimeEnv({
envsubstTemplate: true,
}),
```
When `true` the plugin will create the following template file:
```js
export default {
APP_KEY: $APP_KEY,
};
```
## runtimeHtml
### Summary
This plugin allows an easy way to inject html into `index.html` at compile time based on the [vite mode](https://vitejs.dev/guide/env-and-mode.html).
This is useful for scripts like google tag manager that should only be loaded for certain environments like production.
### Usage
#### vite.config
The plugin options can be injected in the constructor or as a separate object on the vite config object.
```ts
import { runtimeHtml } from 'vite-plugin-runtime';
export default defineConfig({
plugins: [
runtimeHtml(),
],
runtimeHtml: {}, // optional configuration object
```
### Configuration
see [HtmlTagDescriptor](https://vitejs.dev/guide/api-plugin.html#transformindexhtml)
```ts
mode: HtmlTagDescriptor[]
```
```ts
runtimeHtml({
production: [
{
tag: 'script',
attrs: {
type: 'text/javascript',
src: '/some_file.js',
},
injectTo: 'head',
},
],
staging: [
{
tag: 'title',
children: 'Staging',
}
]
}),
```