esbuild-envfile-plugin

1.0.7 verified Fri May 01 auth: no javascript

An esbuild plugin that automatically loads environment variables from a .env file (found in the current directory or any parent) and merges them with existing process.env variables. The .env variables are made available to the bundled code via ESM imports from the virtual module 'env'. This plugin version 1.0.7 is stable and leverages the dotenv package for parsing (not added to user's project). It differentiates by providing a simple, zero-config solution for esbuild bundling, unlike the more general dotenv or @rollup/plugin-dotenv which require explicit setup. Installation requires esbuild and dotenv as dev dependencies.

Common errors

error Error: Cannot find module 'esbuild-envfile-plugin' ↓

cause Plugin not installed or wrong import path.

fix

Run 'npm install esbuild-envfile-plugin --save-dev' and ensure require path is correct.

error Error: Could not resolve 'env' (mark it as external to exclude it from the bundle, or surround it with a try/catch to handle the error gracefully) ↓

cause The 'env' module is a virtual module that only exists during esbuild bundling. If you try to import it outside of esbuild, it fails.

fix

Only import 'env' in files that are processed by esbuild with the plugin installed.

error Error: The plugin "envFilePlugin" didn't set up a resolver ↓

cause The plugin may not be correctly applied to esbuild. Missing plugins array or plugin not properly included.

fix

Make sure you pass the plugin in the plugins array: plugins: [envFilePlugin].

error Error: Cannot find module 'dotenv' ↓

cause dotenv is not installed but is required by the plugin.

fix

Run 'npm install dotenv --save-dev'.

Warnings

gotcha Virtual module 'env' is only available during esbuild bundling. Do not import 'env' in source files that are not bundled by esbuild. ↓

fix Ensure all files importing 'env' are included in the esbuild build entry points.

gotcha The plugin uses 'dotenv' internally, but you must still install 'dotenv' as a devDependency. It is not a direct dependency of the plugin. ↓

fix Run 'npm install dotenv --save-dev' in your project.

gotcha Environment variables from .env override existing process.env variables only if not already set. The merge order: .env values are set only if the variable is not already in process.env. ↓

fix To force override, set the variable in process.env before calling esbuild, or modify the .env file.

gotcha The plugin only works with Node.js platform (esbuild platform: 'node'). Do not use with 'browser' platform as the 'env' virtual module may not work correctly. ↓

fix Set esbuild platform to 'node' or omit platform setting (defaults to browser).

Install

npm install esbuild-envfile-plugin

yarn add esbuild-envfile-plugin

pnpm add esbuild-envfile-plugin

Imports

envFilePlugin
wrong
```
import envFilePlugin from 'esbuild-envfile-plugin';
```
correct
```
const envFilePlugin = require('esbuild-envfile-plugin');
```
This package is CommonJS-only. Using ES import syntax will fail unless your bundler handles it. The default export is the plugin function.
environment variables
wrong
```
import { MY_VAR } from 'esbuild-envfile-plugin';
```
correct
```
import { MY_VAR } from 'env';
```
Virtual module 'env' is created by the plugin. Import from 'env', not from the package itself.
all env variables
wrong
```
import env from 'env';
```
correct
```
import * as env from 'env';
```
For default import of all env vars, use namespace import. Default import is not supported for the virtual module.

Quickstart

Shows installation, esbuild configuration with the plugin, and usage of environment variables from the virtual 'env' module.

// Install: npm install esbuild esbuild-envfile-plugin dotenv --save-dev

// build.js (CJS)
const envFilePlugin = require('esbuild-envfile-plugin');
require('esbuild').build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [envFilePlugin],
}).catch(() => process.exit(1));

// src/index.js (ESM in bundled output)
import { API_KEY } from 'env';
console.log(API_KEY);