esbuild-plugin-auto-env

0.3.0 verified Fri May 01 auth: no javascript

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.

Common errors

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

cause Missing installation or incorrect import path.

fix

Run npm install -D esbuild-plugin-auto-env and use correct import: import { autoEnv } from 'esbuild-plugin-auto-env'.

error SyntaxError: Unexpected token 'export' ↓

cause Using CommonJS require() on an ESM-only package.

fix

Convert to ESM (use import syntax) or use dynamic import: const { autoEnv } = await import('esbuild-plugin-auto-env');

error TypeError: (0 , autoEnv) is not a function ↓

cause Using a default import instead of named import.

fix

Use named import: import { autoEnv } from 'esbuild-plugin-auto-env';

error The plugin 'autoEnv' is not returning a valid esbuild plugin object. ↓

cause Passing incorrect options or calling autoEnv() without parentheses.

fix

Ensure you call autoEnv() as a function: plugins: [autoEnv()].

Warnings

breaking When using `browser` platform, undefined environment variables are replaced with the string `undefined` (not `undefined` value), which may cause bugs. ↓

fix Avoid relying on this behavior; define all expected environment variables, or use `ignore` to prevent replacement.

breaking 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`. ↓

fix Review your include/exclude patterns to ensure they match intended files with the new glob implementation.

deprecated The `cwd` option was removed in v0.2.0; use esbuild's `absWorkingDir` option instead. ↓

fix Remove `cwd` from plugin options and use esbuild's `absWorkingDir` config.

gotcha 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. ↓

fix Ensure all env var references use the exact `process.env.VAR_NAME` syntax.

gotcha The default `include` pattern includes only files under `src/`. If your source files are elsewhere, they will not be scanned for env vars. ↓

fix Explicitly set `include` to match your source directory (e.g., `include: ['lib/**/*.{js,ts}']`).

Install

npm install esbuild-plugin-auto-env

yarn add esbuild-plugin-auto-env

pnpm add esbuild-plugin-auto-env

Imports

autoEnv

wrong

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

correct

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

Package is ESM-only; CJS require() will not work. Use import syntax.

autoEnv (default import)
```
import autoEnv from 'esbuild-plugin-auto-env'
```
Package does not export a default export. Must use named import.

Quickstart

Shows basic usage of autoEnv plugin with esbuild, replacing environment variables in src directory with build-time values.

import esbuild from 'esbuild';
import { autoEnv } from 'esbuild-plugin-auto-env';

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