{"id":21239,"library":"esbuild-plugin-environment","title":"esbuild-plugin-environment","description":"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.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/webdeveric/esbuild-plugin-environment","tags":["javascript","esbuild","plugin","environment","typescript"],"install":[{"cmd":"npm install esbuild-plugin-environment","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-environment","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-environment","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for plugin system compatibility","package":"esbuild","optional":false}],"imports":[{"note":"ESM-only since v0.5.0; use dynamic import() in CJS projects","wrong":"const environmentPlugin = require('esbuild-plugin-environment')","symbol":"environmentPlugin","correct":"import { environmentPlugin } from 'esbuild-plugin-environment'"},{"note":"Types are exported, but cannot be used as runtime values","wrong":"import { EnvironmentPluginOptions } from 'esbuild-plugin-environment'","symbol":"environmentPlugin (type import)","correct":"import type { EnvironmentPluginOptions } from 'esbuild-plugin-environment'"},{"note":"No default export; named export only","wrong":"import environmentPlugin from 'esbuild-plugin-environment'","symbol":"default export (not provided)","correct":"import { environmentPlugin } from 'esbuild-plugin-environment'"}],"quickstart":{"code":"import { environmentPlugin } from 'esbuild-plugin-environment';\nimport * as esbuild from 'esbuild';\n\nawait esbuild.build({\n  entryPoints: ['app.ts'],\n  bundle: true,\n  outfile: 'out.js',\n  plugins: [\n    environmentPlugin({\n      API_URL: process.env.API_URL ?? 'http://localhost:3000',\n      NODE_ENV: 'production',\n    }),\n  ],\n});","lang":"typescript","description":"Shows ESM usage with object map: defines API_URL (with fallback) and NODE_ENV as build-time constants."},"warnings":[{"fix":"Upgrade esbuild to version 0.15 or higher","message":"Requires esbuild >= 0.15 for peer dependency compatibility","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Use dynamic import or switch project to ESM","message":"CommonJS require() may fail due to ESM-only export in v0.5.0","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Upgrade Node.js to 20 or later","message":"Node.js <20 is no longer supported","severity":"deprecated","affected_versions":">=0.5.0"},{"fix":"Pass object map with fallbacks or ensure environment variables are set before build","message":"environmentPlugin replaces process.env references literally; does not read actual process.env at build time for array keys","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use esbuild's external or exclude plugin for specific dependencies","message":"npm packages may have their own process.env usage that gets inappropriately replaced in bundled output","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Ensure environmentPlugin is the first plugin in the plugins array","cause":"Misconfigured environmentPlugin or alternative plugin interference","error":"ReferenceError: __esbuild_plugin_environment is not defined"},{"fix":"Add inject plugin with process polyfill instead of environmentPlugin for browser targets","cause":"Missing process polyfill in browser builds","error":"Error: [plugin: environment-plugin] Cannot find module 'process'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}