rollup-plugin-inject-process-env

1.3.1 verified Mon Apr 27 auth: no javascript

Rollup plugin to inject process.env environment variables into browser bundles. Version 1.3.1 supports any JSON-serializable value (not just strings), handles all access patterns including bracket notation and destructuring, and works with include/exclude minimatch patterns. Unlike rollup-plugin-replace, it avoids lint issues from string-to-string substitution. Requires placement after @rollup/plugin-commonjs when used together. Ships TypeScript types.

Common errors

error 'import' and 'export' may only appear at the top level ↓

cause injectProcessEnv was placed before @rollup/plugin-commonjs in the plugins array.

fix

Reorder plugins so that commonjs() appears before injectProcessEnv()

error 'globalThis' is undefined ↓

cause The target environment does not support globalThis.

fix

Add a polyfill for globalThis, e.g., import '@ungap/global-this' at the top of your entry file.

error Cannot find module 'rollup-plugin-inject-process-env' ↓

cause Package not installed or require() used instead of import.

fix

Run npm install --save-dev rollup-plugin-inject-process-env and use ESM import syntax.

error process.env is not defined ↓

cause The plugin was not applied correctly or the bundle is run in a browser without the injection.

fix

Ensure injectProcessEnv is called in the plugins array with the correct env object.

Warnings

breaking Plugin must be placed after @rollup/plugin-commonjs in plugins array, otherwise you'll get 'import' and 'export' may only appear at the top level error. ↓

fix Move injectProcessEnv() after commonjs() in the plugins list.

deprecated The default export name changed from 'injectProcessEnv' to 'injectProcessEnv' (same) but no longer supports named exports. Older versions had both default and named exports. ↓

fix Use default import only: import injectProcessEnv from 'rollup-plugin-inject-process-env'

gotcha This plugin does not read .env files automatically. You must pass the env object explicitly. ↓

fix Combine with dotenv or load environment variables manually before calling injectProcessEnv.

gotcha When using with @rollup/plugin-replace, order matters. injectProcessEnv should run after replace to avoid conflicts. ↓

fix Place injectProcessEnv after replace in the plugins array.

gotcha globalThis may be undefined in older browsers/environments, causing runtime errors. ↓

fix Install and import a globalThis polyfill like @ungap/global-this.

Install

npm install rollup-plugin-inject-process-env

yarn add rollup-plugin-inject-process-env

pnpm add rollup-plugin-inject-process-env

Imports

injectProcessEnv

wrong

const injectProcessEnv = require('rollup-plugin-inject-process-env')

correct

import injectProcessEnv from 'rollup-plugin-inject-process-env'

Default export; ESM-only since v1. CommonJS require will not work. TypeScript types are included.

RollupPluginInjectProcessEnvOptions

wrong

import { RollupPluginInjectProcessEnvOptions } from 'rollup-plugin-inject-process-env'

correct

import type { RollupPluginInjectProcessEnvOptions } from 'rollup-plugin-inject-process-env'

Type-only import; do not use value import for types.

injectProcessEnv (as plugin)
wrong
```
new injectProcessEnv({ NODE_ENV: 'production' })
```
correct
```
injectProcessEnv({ NODE_ENV: 'production' })
```
injectProcessEnv is a function, not a class. Do not use 'new'.

Quickstart

Shows basic usage with Rollup config using TypeScript, CommonJS, and resolve plugins. Plugin order matters: injectProcessEnv must come after commonjs.

import injectProcessEnv from 'rollup-plugin-inject-process-env';
import commonjs from '@rollup/plugin-commonjs';
import resolve from '@rollup/plugin-node-resolve';
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  output: {
    file: 'dist/bundle.js',
    format: 'iife'
  },
  plugins: [
    typescript(),
    commonjs(),
    injectProcessEnv({
      NODE_ENV: process.env.NODE_ENV ?? 'development',
      API_URL: JSON.parse(process.env.API_URL ?? '"http://localhost:3000"'),
      DEBUG: false
    }),
    resolve()
  ]
};