{"id":25313,"library":"esbuild-plugin-auto-env","title":"esbuild-plugin-auto-env","description":"An esbuild plugin that automatically replaces environment variable references in source code with values defined at build time. Current stable version is 0.3.0, released September 2023. Update cadence is irregular. Key differentiators: supports glob-based include/exclude patterns for fine-grained control, allows ignoring specific environment variables, and replaces with undefined in browser mode. Alternative to manual Define or envsubst approaches. Ships TypeScript types.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/harrydowning/esbuild-plugin-auto-env","tags":["javascript","esbuild","plugin","env","typescript"],"install":[{"cmd":"npm install esbuild-plugin-auto-env","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-auto-env","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-auto-env","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required to use the plugin","package":"esbuild","optional":false}],"imports":[{"note":"Package is ESM-only; CJS require() will not work. Use import syntax.","wrong":"const autoEnv = require('esbuild-plugin-auto-env')","symbol":"autoEnv","correct":"import { autoEnv } from 'esbuild-plugin-auto-env'"},{"note":"Package does not export a default export. Must use named import.","wrong":"","symbol":"autoEnv (default import)","correct":"import autoEnv from 'esbuild-plugin-auto-env'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport { autoEnv } from 'esbuild-plugin-auto-env';\n\nawait esbuild.build({\n  entryPoints: ['src/index.js'],\n  outfile: 'dist/index.js',\n  bundle: true,\n  plugins: [autoEnv()],\n});","lang":"typescript","description":"Shows basic usage of autoEnv plugin with esbuild, replacing environment variables in src directory with build-time values."},"warnings":[{"fix":"Avoid relying on this behavior; define all expected environment variables, or use `ignore` to prevent replacement.","message":"When using `browser` platform, undefined environment variables are replaced with the string `undefined` (not `undefined` value), which may cause bugs.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Review your include/exclude patterns to ensure they match intended files with the new glob implementation.","message":"In v0.3.0, include and exclude now support glob patterns using node-glob syntax; previous versions used simple strings. This changes behavior for patterns like `src/**/*.js`.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Remove `cwd` from plugin options and use esbuild's `absWorkingDir` config.","message":"The `cwd` option was removed in v0.2.0; use esbuild's `absWorkingDir` option instead.","severity":"deprecated","affected_versions":"<0.2.0"},{"fix":"Ensure all env var references use the exact `process.env.VAR_NAME` syntax.","message":"Environment variables are only replaced if they appear as `process.env.VAR_NAME`. Other patterns (e.g., `process.env['VAR_NAME']` or destructured variables) are not replaced.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Explicitly set `include` to match your source directory (e.g., `include: ['lib/**/*.{js,ts}']`).","message":"The default `include` pattern includes only files under `src/`. If your source files are elsewhere, they will not be scanned for env vars.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install -D esbuild-plugin-auto-env` and use correct import: `import { autoEnv } from 'esbuild-plugin-auto-env'`.","cause":"Missing installation or incorrect import path.","error":"Error: Cannot find module 'esbuild-plugin-auto-env'"},{"fix":"Convert to ESM (use import syntax) or use dynamic import: `const { autoEnv } = await import('esbuild-plugin-auto-env');`","cause":"Using CommonJS require() on an ESM-only package.","error":"SyntaxError: Unexpected token 'export'"},{"fix":"Use named import: `import { autoEnv } from 'esbuild-plugin-auto-env';`","cause":"Using a default import instead of named import.","error":"TypeError: (0 , autoEnv) is not a function"},{"fix":"Ensure you call autoEnv() as a function: `plugins: [autoEnv()]`.","cause":"Passing incorrect options or calling autoEnv() without parentheses.","error":"The plugin 'autoEnv' is not returning a valid esbuild plugin object."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}