Registry / web-framework / esbuild-plugin-env

esbuild-plugin-env

library1.1.1jsnpmunverified

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.

web-framework devops serialization

npm install esbuild-plugin-env

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-ENV

esbuild-plugin-env

web-frameworkjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

env

✓ import env from 'esbuild-plugin-env'

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

Default export only; named import will result in undefined.

env

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

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

CJS require returns the default export directly; destructuring breaks.

type EnvOptions

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

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

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

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

Debug

Known issues

breakingIn 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.

affects: >=1.1.0

deprecatedThe 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).

affects: >=1.0.0

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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

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

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: No env file found

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.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

dotenvrequiredruntime dependency for loading .env files

esbuildrequiredpeer dependency required to use as plugin

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/yamitsushi/esbuild-plugin-env ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-env ↗