rollup-plugin-process-env

1.0.7 verified Mon Apr 27 auth: no javascript

A Rollup plugin that injects `process.env` variables into the build. Current stable version is 1.0.7 (released 2023). It supports prefix-based filtering, custom filter functions, or direct object mapping. Unlike @rollup/plugin-replace or @rollup/plugin-inject, this plugin specifically handles `process.env` references and offers built-in dotenv integration guidance. Ships TypeScript types. Release cadence is low; updates are infrequent. Key differentiators: simple API, no additional configuration for common use cases, and explicit support for dotenv/dotenv-expand.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/rollup-plugin-process-env/dist/index.mjs from /path/to/rollup.config.js not supported. ↓

cause Trying to require() the plugin in a CommonJS context; plugin is ESM-only since v1.0.0.

fix

Rename rollup.config.js to rollup.config.mjs or set "type": "module" in package.json, then use import syntax.

error TypeError: (0 , rollup_plugin_process_env.default) is not a function ↓

cause Using named import { env } instead of default import.

fix

Use import env from 'rollup-plugin-process-env' without curly braces.

error Uncaught ReferenceError: process is not defined ↓

cause The plugin runs at build time; runtime references to `process` outside of replaced variables remain if the environment does not define `process`.

fix

Ensure your target environment supports process, or use a polyfill like @rollup/plugin-inject to define process globally.

Warnings

gotcha The plugin only replaces `process.env` references that appear exactly as `process.env.VAR_NAME`. Dynamic accesses like `process.env['VAR_NAME']` or `process.env[varName]` are NOT replaced. ↓

fix Use only dot notation with static property names, or use a different plugin (e.g., @rollup/plugin-replace) for dynamic patterns.

gotcha When using dotenv, you must manually call dotenv expansion before importing the plugin; the plugin itself does not load .env files. ↓

fix Add `require('dotenv-expand').expand(require('dotenv').config())` at the top of your config file.

deprecated The plugin does not handle `process.env` reassignment (e.g., `const env = process.env; env.NODE_ENV`). Only direct `process.env.X` references are replaced. ↓

fix Always use `process.env.X` directly in your code.

breaking Version 1.0.0 switched to ESM-only distribution. If using CommonJS require, the import fails. ↓

fix Use `import env from 'rollup-plugin-process-env'` in an ESM context (enable ESM in your package.json or use .mjs extension).

Install

npm install rollup-plugin-process-env

yarn add rollup-plugin-process-env

pnpm add rollup-plugin-process-env

Imports

default

wrong

const env = require('rollup-plugin-process-env');

correct

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

ESM-only; CommonJS require not supported by the plugin's packaging.

env as function

wrong

import { env } from 'rollup-plugin-process-env';

correct

import env from 'rollup-plugin-process-env';
plugins: [ env('MY_PREFIX_') ]

The plugin exports a default function; named import { env } will be undefined.

type definitions

wrong

import { Options } from 'rollup-plugin-process-env';

correct

import type { Options } from 'rollup-plugin-process-env'

TypeScript types are included; but Options is not a runtime export, it's a type.

Quickstart

Basic Rollup configuration that uses the plugin to inject two custom environment variables into the bundle.

import env from 'rollup-plugin-process-env';

export default {
  input: 'src/index.js',
  output: { file: 'dist/bundle.js', format: 'es' },
  plugins: [ env({ MY_VAR: 'hello', ANOTHER: 'world' }) ]
};