Registry / devops / esbuild-plugin-environment

esbuild-plugin-environment

library0.5.0jsnpmunverified

esbuild plugin that replaces process.env references with environment variable values at build time. Supports both object maps (key → default value) and arrays of keys. Version 0.5.0 is the latest stable release, with active maintenance. Key differentiators: simple API, supports both Node.js and browser targets, ships TypeScript definitions, and integrates seamlessly with esbuild's plugin system. The plugin is lightweight and focuses exclusively on environment variable injection, unlike more complex solutions like dotenv or webpack's DefinePlugin.

devops serialization

npm install esbuild-plugin-environment

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-ENV

esbuild-plugin-environment

devopsjavascriptv0.5.0

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.

environmentPlugin

✓ import { environmentPlugin } from 'esbuild-plugin-environment'

✗ const environmentPlugin = require('esbuild-plugin-environment')

ESM-only since v0.5.0; use dynamic import() in CJS projects

environmentPlugin (type import)

✓ import type { EnvironmentPluginOptions } from 'esbuild-plugin-environment'

✗ import { EnvironmentPluginOptions } from 'esbuild-plugin-environment'

Types are exported, but cannot be used as runtime values

default export (not provided)

✓ import { environmentPlugin } from 'esbuild-plugin-environment'

✗ import environmentPlugin from 'esbuild-plugin-environment'

No default export; named export only

Shows ESM usage with object map: defines API_URL (with fallback) and NODE_ENV as build-time constants.

import { environmentPlugin } from 'esbuild-plugin-environment'; import * as esbuild from 'esbuild'; await esbuild.build({ entryPoints: ['app.ts'], bundle: true, outfile: 'out.js', plugins: [ environmentPlugin({ API_URL: process.env.API_URL ?? 'http://localhost:3000', NODE_ENV: 'production', }), ], });

Debug

Known issues

breakingRequires esbuild >= 0.15 for peer dependency compatibility

fix

Upgrade esbuild to version 0.15 or higher

affects: >=0.5.0

breakingCommonJS require() may fail due to ESM-only export in v0.5.0

fix

Use dynamic import or switch project to ESM

affects: >=0.5.0

deprecatedNode.js <20 is no longer supported

fix

Upgrade Node.js to 20 or later

affects: >=0.5.0

gotchaenvironmentPlugin replaces process.env references literally; does not read actual process.env at build time for array keys

fix

Pass object map with fallbacks or ensure environment variables are set before build

affects: >=0.0.0

gotchanpm packages may have their own process.env usage that gets inappropriately replaced in bundled output

fix

Use esbuild's external or exclude plugin for specific dependencies

affects: >=0.0.0

Errors

Common errors & fixes

ReferenceError: __esbuild_plugin_environment is not defined

Misconfigured environmentPlugin or alternative plugin interference

fix

Ensure environmentPlugin is the first plugin in the plugins array

Error: [plugin: environment-plugin] Cannot find module 'process'

Missing process polyfill in browser builds

fix

Add inject plugin with process polyfill instead of environmentPlugin for browser targets

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency required for plugin system compatibility

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/webdeveric/esbuild-plugin-environment ↗

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