Registry / devops / esbuild-envfile-plugin

esbuild-envfile-plugin

library1.0.7jsnpmunverified

An esbuild plugin that automatically loads environment variables from a .env file (found in the current directory or any parent) and merges them with existing process.env variables. The .env variables are made available to the bundled code via ESM imports from the virtual module 'env'. This plugin version 1.0.7 is stable and leverages the dotenv package for parsing (not added to user's project). It differentiates by providing a simple, zero-config solution for esbuild bundling, unlike the more general dotenv or @rollup/plugin-dotenv which require explicit setup. Installation requires esbuild and dotenv as dev dependencies.

devops

npm install esbuild-envfile-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-ENVFILE-PL

esbuild-envfile-plugin

devopsjavascriptv1.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

envFilePlugin

✓ const envFilePlugin = require('esbuild-envfile-plugin');

✗ import envFilePlugin from 'esbuild-envfile-plugin';

This package is CommonJS-only. Using ES import syntax will fail unless your bundler handles it. The default export is the plugin function.

environment variables

✓ import { MY_VAR } from 'env';

✗ import { MY_VAR } from 'esbuild-envfile-plugin';

Virtual module 'env' is created by the plugin. Import from 'env', not from the package itself.

all env variables

✓ import * as env from 'env';

✗ import env from 'env';

For default import of all env vars, use namespace import. Default import is not supported for the virtual module.

Shows installation, esbuild configuration with the plugin, and usage of environment variables from the virtual 'env' module.

// Install: npm install esbuild esbuild-envfile-plugin dotenv --save-dev // build.js (CJS) const envFilePlugin = require('esbuild-envfile-plugin'); require('esbuild').build({ entryPoints: ['src/index.js'], bundle: true, outfile: 'dist/bundle.js', plugins: [envFilePlugin], }).catch(() => process.exit(1)); // src/index.js (ESM in bundled output) import { API_KEY } from 'env'; console.log(API_KEY);

Debug

Known issues

gotchaVirtual module 'env' is only available during esbuild bundling. Do not import 'env' in source files that are not bundled by esbuild.

fix

Ensure all files importing 'env' are included in the esbuild build entry points.

affects: >=1.0.0

gotchaThe plugin uses 'dotenv' internally, but you must still install 'dotenv' as a devDependency. It is not a direct dependency of the plugin.

fix

Run 'npm install dotenv --save-dev' in your project.

affects: >=1.0.0

gotchaEnvironment variables from .env override existing process.env variables only if not already set. The merge order: .env values are set only if the variable is not already in process.env.

fix

To force override, set the variable in process.env before calling esbuild, or modify the .env file.

affects: >=1.0.0

gotchaThe plugin only works with Node.js platform (esbuild platform: 'node'). Do not use with 'browser' platform as the 'env' virtual module may not work correctly.

fix

Set esbuild platform to 'node' or omit platform setting (defaults to browser).

affects: >=1.0.0

Errors

Common errors & fixes

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

Plugin not installed or wrong import path.

fix

Run 'npm install esbuild-envfile-plugin --save-dev' and ensure require path is correct.

Error: Could not resolve 'env' (mark it as external to exclude it from the bundle, or surround it with a try/catch to handle the error gracefully)

The 'env' module is a virtual module that only exists during esbuild bundling. If you try to import it outside of esbuild, it fails.

fix

Only import 'env' in files that are processed by esbuild with the plugin installed.

Error: The plugin "envFilePlugin" didn't set up a resolver

The plugin may not be correctly applied to esbuild. Missing plugins array or plugin not properly included.

fix

Make sure you pass the plugin in the plugins array: plugins: [envFilePlugin].

Error: Cannot find module 'dotenv'

dotenv is not installed but is required by the plugin.

fix

Run 'npm install dotenv --save-dev'.

Upgrade

Version history

1.0.7latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency required for the plugin to work. esbuild must be installed and available as the build tool.

dotenvrequiredUsed internally by the plugin to parse .env files. Must be installed by the user as a dev dependency.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/rw3iss/esbuild-envfile-plugin ↗

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