Registry / devops / vite-inject-env

vite-inject-env

library2.1.0jsnpmunverified

vite-inject-env is a build tool designed to address a common challenge in modern web application deployment, particularly for Vite-based projects. It enables the injection of environment variables *after* the static files have been built, rather than requiring them at build time. This allows developers to create a single, immutable build artifact that can be deployed to multiple environments (e.g., development, staging, production) with different configurations, promoting a more efficient and reliable CI/CD workflow. The current stable version is 2.1.0, and while a specific release cadence isn't published, the presence of distinct v1.0 and v2.0 documentation suggests major versions are released to incorporate significant architectural or feature updates. A key differentiator is its synchronous availability of environment variables in the browser without the need for asynchronous fetching, resolving a limitation often encountered with other post-build environment variable solutions.

devops

npm install vite-inject-env

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-INJECT-ENV

vite-inject-env

devopsjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

env

✓ import { env } from './env'

✗ const env = require('./env');

The 'env' object is a custom export from a user-created 'env.js' or 'env.ts' file, not directly from the 'vite-inject-env' package itself. This file merges 'import.meta.env' with 'window.env'.

vite-inject-env CLI

✓ npx vite-inject-env set

✗ import { set } from 'vite-inject-env'

The primary interaction with 'vite-inject-env' is via its Command Line Interface (CLI) tool 'npx vite-inject-env set', which is run after the Vite build process. There are no direct code imports from the package for runtime use within your application.

Window.env (TypeScript)

✓ declare global { interface Window { env: any } }

✗ interface Window { env: any } // without declare global

For TypeScript projects, it's crucial to augment the global Window interface to correctly type the 'window.env' object that 'vite-inject-env' places there. This ensures type safety when accessing environment variables.

This quickstart demonstrates how to integrate `vite-inject-env` into a Vite project, showing the necessary `index.html` modification, the `env.ts` file setup, and how to use the `env` object in a component. It also illustrates the post-build CLI command for injecting variables.

import { env } from './env'; // 1. Create env.js (or env.ts) in your project root: // export const env = { ...import.meta.env, ...window['env'] }; // 2. Add this script tag to your public/index.html: // <script src='/env.js'></script> // 3. Your App component or any other file can now use 'env': export const App = () => { const bgColor = env.VITE_COLOR || 'white'; const mainText = env.VITE_MAIN_TEXT || 'Hello Vite!'; return ( <div style={{ backgroundColor: bgColor, padding: '20px', minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center' }}> <span style={{ fontSize: '2em', color: 'darkslategray' }}>{mainText}</span> </div> ); }; // 4. Build your Vite application: // npm run build // 5. Inject environment variables after build: // VITE_COLOR=lightcoral VITE_MAIN_TEXT="Welcome to a new environment!" npx vite-inject-env set

Debug

Known issues

breakingVersion 2.0 introduced significant changes compared to v1.0. If you are upgrading from v1, review the official v1.0 guide to understand the differences and update your implementation accordingly.

fix

Consult the 'v1.0 guide' linked in the README for migration details. The usage patterns, especially for the custom `env.js`/`env.ts` file, have likely changed.

affects: >=2.0.0

gotchaEnvironment variables passed directly via the command line (e.g., `VITE_COLOR=black npx vite-inject-env set`) will always take precedence over variables defined in any `.env` files detected by `vite-inject-env`.

fix

Be mindful of the order of precedence. If you intend for `.env` files to be the primary source, ensure no conflicting variables are passed through the command line during the injection step.

affects: >=1.0.0

gotchaThe tool outputs environment variables into `window.env` by default. If your application or other libraries already use `window.env`, this can lead to conflicts and unexpected behavior.

fix

Use the `-v` or `--var` option with the `vite-inject-env set` command to specify an alternative variable name (e.g., `npx vite-inject-env set -v myCustomEnv`). Remember to update your `env.js`/`env.ts` file to use this new window property.

affects: >=1.0.0

gotchaIt is critical to include `<script src='/env.js'></script>` (or your custom filename/path) in your `index.html` file. Without this script, the `window.env` object will not be populated, leading to undefined variables in your application.

fix

Ensure the script tag is present in your main HTML file and points to the correct path where `vite-inject-env` will generate the `env.js` file (defaulting to `/env.js` relative to your build output).

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: env is not defined

The `env` variable was imported or used, but the `env.js` (or `env.ts`) file was not created, or the `<script>` tag referencing it was omitted from `index.html`, or the injection step was not run.

fix

Ensure you have created the `env.js` (or `env.ts`) file as specified in the usage instructions, added `<script src='/env.js'></script>` to `index.html`, and executed `npx vite-inject-env set` after building your application.

TypeScript Error: Property 'VITE_MY_VARIABLE' does not exist on type 'EnvType'.

When using TypeScript, the `EnvType` definition in `env.ts` does not include all the environment variables you are attempting to access.

fix

Update the `EnvType` interface in your `env.ts` file to include all expected environment variables and their types. For example, add `VITE_MY_VARIABLE: string;` to the interface.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/rafyzg/vite-inject-env ↗

packagehttps://www.npmjs.com/package/vite-inject-env ↗