rollup-plugin-dotenv

0.5.1 verified Mon Apr 27 auth: no javascript

Rollup plugin that loads .env files and replaces process.env references at build time. Current stable version is 0.5.1. Released irregularly, with the last release in 2023. It integrates with @rollup/plugin-replace under the hood for environment variable substitution. Supports multiple .env files with environment-specific overrides (e.g., .env.production.local). Unlike runtime dotenv packages, this plugin performs compile-time replacement, which can improve performance and security. No browser or client-side usage. Only supports CommonJS requires? Note: This plugin does not support dynamic access like process.env[VAR]. Shipping TypeScript types.

Common errors

error Error: [plugin-replace] You must specify a values object or a delimiters array. ↓

cause Missing or misconfigured options passed to the plugin. The plugin expects certain internal configuration.

fix

Ensure you call dotenv() without arguments or with valid options. If you pass custom options, they must include valid keys.

error TypeError: dotenv is not a function ↓

cause Using incorrect import style, e.g., importing { dotenv } instead of default.

fix

Use import dotenv from 'rollup-plugin-dotenv' or const dotenv = require('rollup-plugin-dotenv').

error Error: Could not resolve './.env' ↓

cause The .env file is not found at the expected location.

fix

Ensure .env files exist in the current working directory or set the cwd option to the correct directory.

Warnings

gotcha Dynamic access like `process.env[VAR]` will NOT be replaced. Only static references like `process.env.FOO` are handled. ↓

fix Use static property access for env vars that should be replaced at build time.

gotcha The plugin uses @rollup/plugin-replace, which can have unexpected side effects if the same variable name appears in other contexts. ↓

fix Avoid using process.env.VAR names that might conflict with other strings in your code.

breaking Version 0.5.0 dropped support for Rollup < 1.20.0. ↓

fix Upgrade Rollup to >= 1.20.0 or use older version of the plugin.

gotcha The plugin only replaces in bundled output, not in source code. process.env references remain in source during development. ↓

fix Use runtime dotenv for development if needed, or configure Rollup to replace only in production builds.

Install

npm install rollup-plugin-dotenv

yarn add rollup-plugin-dotenv

pnpm add rollup-plugin-dotenv

Imports

default
wrong
```
const dotenv = require('rollup-plugin-dotenv')
```
correct
```
import dotenv from 'rollup-plugin-dotenv'
```
The default export is a function that returns the Rollup plugin. In CJS, use require to get the default, but ESM style is preferred.
dotenv
wrong
```
const { dotenv } = require('rollup-plugin-dotenv')
```
correct
```
const dotenv = require('rollup-plugin-dotenv')
```
Destructuring the require is incorrect as the module exports a single function as default.

Types

import type { RollupPluginDotenvOptions } from 'rollup-plugin-dotenv'

TypeScript types are available; you can import types for options.

Quickstart

Basic Rollup configuration using rollup-plugin-dotenv to replace process.env references with values from .env files.

// rollup.config.js
import dotenv from 'rollup-plugin-dotenv';

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  },
  plugins: [
    dotenv({
      cwd: '.',
      envKey: 'NODE_ENV'
    })
  ]
};