babel-plugin-transform-vite-meta-env

1.0.3 verified Sat Apr 25 auth: no javascript maintenance

Babel plugin that emulates Vite's import.meta.env functionality for non-Vite environments, such as testing with NodeJS-based runners. Version 1.0.3 is the latest stable release, last updated in April 2021. It transforms import.meta.env.MODE, .BASE_URL, .DEV, .PROD, etc. into process.env references or static values, providing an approximation of Vite's env behavior. Differentiated from alternatives like @rollup/plugin-replace by specifically targeting Vite idioms and supporting a set of predefined env variables. Release cadence is low; part of the babel-vite monorepo. Ships TypeScript types.

Common errors

error Cannot find module 'babel-plugin-transform-vite-meta-env' ↓

cause Package not installed or incorrectly specified in babel config.

fix

Run 'npm install --save-dev babel-plugin-transform-vite-meta-env' and ensure it's in package.json devDependencies.

error import.meta.env is not defined ↓

cause Plugin not applied or not transforming code (e.g., running in browser without bundler).

fix

Verify Babel configuration includes the plugin and that you are transforming the file (e.g., using @babel/register or build step).

error TypeError: Cannot read properties of undefined (reading 'env') ↓

cause Plugin didn't transform; code is executed in a context where import.meta is undefined (e.g., older Node.js).

fix

Ensure Babel runs on the file and the plugin is active. For Node.js <14, upgrade or use @babel/plugin-syntax-import-meta.

Warnings

gotcha Does not handle import.meta.env.SSR or import.meta.env.PROD correctly when NODE_ENV is not set; DEV may be truthy in test environments. ↓

fix Set NODE_ENV explicitly to 'production' or 'development' before running tests.

gotcha Plugin only replaces specific keys; unknown keys (e.g., import.meta.env.OTHER) are replaced with undefined, not the full env object. ↓

fix Define all used env variables in your Vite config and ensure they are prefixed with VITE_, or handle undefined cases in code.

deprecated Part of babel-preset-vite which is in maintenance mode; consider using vitest or jest with vite plugins for better integration. ↓

fix Migrate tests to Vitest, which natively resolves import.meta.env.

deprecated Use of process.env.NODE_ENV fallback to 'test' may not reflect actual environment. ↓

fix Set NODE_ENV explicitly in test scripts (e.g., "test": "NODE_ENV=test jest").

Install

npm install babel-plugin-transform-vite-meta-env

yarn add babel-plugin-transform-vite-meta-env

pnpm add babel-plugin-transform-vite-meta-env

Imports

default

wrong

const plugin = require('babel-plugin-transform-vite-meta-env')

correct

import plugin from 'babel-plugin-transform-vite-meta-env'

Plugin is a default export; works with both ESM and CJS require, but import is preferred for TypeScript.

Quickstart

Configures Babel to replace import.meta.env references with process.env equivalents or static values, useful for testing Vite-dependent code in non-Vite environments.

// babel.config.js
module.exports = {
  plugins: ['babel-plugin-transform-vite-meta-env'],
};

// input.js (before)
const mode = import.meta.env.MODE;
const baseUrl = import.meta.env.BASE_URL;
const dev = import.meta.env.DEV;
const prod = import.meta.env.PROD;
const viteVar = import.meta.env.VITE_VAR;
const other = import.meta.env.OTHER;

// output.js (after)
const mode = process.env.MODE;
const baseUrl = '/';
const dev = process.env.NODE_ENV !== 'production';
const prod = process.env.NODE_ENV === 'production';
const viteVar = process.env.VITE_VAR;
const other = undefined;