esbuild-plugin-env

1.1.1 verified Mon Apr 27 auth: no javascript

ESBuild plugin (v1.1.1, maintained) that loads environment variables using dotenv and makes them available via process.env at build time. Key differentiators: automatically sets NODE_ENV based on minify flag, provides PROD/DEV boolean constants, supports custom key prefix (default ESB_), and allows overriding production detection. Ships TypeScript types. Alternative to @jvdx/esbuild-plugin-env or manual define replacements.

Common errors

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

cause Package not installed or incorrect import path.

fix

Run npm install esbuild-plugin-env --save-dev or check that the package is listed in devDependencies.

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

cause Named import instead of default import.

fix

Use import env from 'esbuild-plugin-env' (default import) instead of import { env } from 'esbuild-plugin-env'.

error Error: No env file found ↓

cause No .env file exists in the current working directory.

fix

Create a .env file in the root of your project or use dotenv's config to specify a path before building.

Warnings

breaking In v1.1.0, the option `startkey` was renamed to `startKey` (camelCase). Using `startkey` will be ignored silently. ↓

fix Use `startKey` instead of `startkey` in the options object.

deprecated The plugin only defines environment variables with a prefix (default `ESB_`). Variables without the prefix are not included. ↓

fix Ensure your .env keys start with `ESB_` (or the configured startKey).

gotcha `process.env.NODE_ENV` is set to 'production' only when `minify: true` or `isProd: true`. Otherwise it remains undefined (not 'development'). ↓

fix Explicitly set `isProd: true` in options if you want production behavior without minification.

gotcha The plugin does not automatically load .env files from custom paths. It uses dotenv's default behavior (looks for .env in cwd). ↓

fix Use dotenv's path option by calling `require('dotenv').config({ path: '/custom/path' })` before running esbuild.

Install

npm install esbuild-plugin-env

yarn add esbuild-plugin-env

pnpm add esbuild-plugin-env

Imports

env

wrong

import { env } from 'esbuild-plugin-env'

correct

import env from 'esbuild-plugin-env'

Default export only; named import will result in undefined.

env

wrong

const { env } = require('esbuild-plugin-env')

correct

const env = require('esbuild-plugin-env')

CJS require returns the default export directly; destructuring breaks.

type EnvOptions

wrong

import { EnvOptions } from 'esbuild-plugin-env'

correct

import type { EnvOptions } from 'esbuild-plugin-env'

Type import only; use `import type` for type-only consumption.

Quickstart

Shows basic usage of esbuild-plugin-env: import, call env() in plugins array, and access variables from .env via process.env.

import esbuild from 'esbuild';
import env from 'esbuild-plugin-env';

await esbuild.build({
  entryPoints: ['./src/index.js'],
  bundle: true,
  minify: true,
  outfile: './dist/bundle.js',
  plugins: [env()],
});

// .env file:
// ESB_API_KEY=abc123
// In source:
// console.log(process.env.ESB_API_KEY); // 'abc123'
// console.log(process.env.PROD); // true
// console.log(process.env.DEV); // false