{"id":25281,"library":"esbuild-envfile-plugin","title":"esbuild-envfile-plugin","description":"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.","status":"active","version":"1.0.7","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/rw3iss/esbuild-envfile-plugin","tags":["javascript","esbuild","esbuild plugin","envfile","env","dotenv"],"install":[{"cmd":"npm install esbuild-envfile-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-envfile-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-envfile-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the plugin to work. esbuild must be installed and available as the build tool.","package":"esbuild","optional":false},{"reason":"Used internally by the plugin to parse .env files. Must be installed by the user as a dev dependency.","package":"dotenv","optional":false}],"imports":[{"note":"This package is CommonJS-only. Using ES import syntax will fail unless your bundler handles it. The default export is the plugin function.","wrong":"import envFilePlugin from 'esbuild-envfile-plugin';","symbol":"envFilePlugin","correct":"const envFilePlugin = require('esbuild-envfile-plugin');"},{"note":"Virtual module 'env' is created by the plugin. Import from 'env', not from the package itself.","wrong":"import { MY_VAR } from 'esbuild-envfile-plugin';","symbol":"environment variables","correct":"import { MY_VAR } from 'env';"},{"note":"For default import of all env vars, use namespace import. Default import is not supported for the virtual module.","wrong":"import env from 'env';","symbol":"all env variables","correct":"import * as env from 'env';"}],"quickstart":{"code":"// Install: npm install esbuild esbuild-envfile-plugin dotenv --save-dev\n\n// build.js (CJS)\nconst envFilePlugin = require('esbuild-envfile-plugin');\nrequire('esbuild').build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [envFilePlugin],\n}).catch(() => process.exit(1));\n\n// src/index.js (ESM in bundled output)\nimport { API_KEY } from 'env';\nconsole.log(API_KEY);","lang":"javascript","description":"Shows installation, esbuild configuration with the plugin, and usage of environment variables from the virtual 'env' module."},"warnings":[{"fix":"Ensure all files importing 'env' are included in the esbuild build entry points.","message":"Virtual module 'env' is only available during esbuild bundling. Do not import 'env' in source files that are not bundled by esbuild.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Run 'npm install dotenv --save-dev' in your project.","message":"The plugin uses 'dotenv' internally, but you must still install 'dotenv' as a devDependency. It is not a direct dependency of the plugin.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To force override, set the variable in process.env before calling esbuild, or modify the .env file.","message":"Environment 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set esbuild platform to 'node' or omit platform setting (defaults to browser).","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.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 esbuild-envfile-plugin --save-dev' and ensure require path is correct.","cause":"Plugin not installed or wrong import path.","error":"Error: Cannot find module 'esbuild-envfile-plugin'"},{"fix":"Only import 'env' in files that are processed by esbuild with the plugin installed.","cause":"The 'env' module is a virtual module that only exists during esbuild bundling. If you try to import it outside of esbuild, it fails.","error":"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)"},{"fix":"Make sure you pass the plugin in the plugins array: plugins: [envFilePlugin].","cause":"The plugin may not be correctly applied to esbuild. Missing plugins array or plugin not properly included.","error":"Error: The plugin \"envFilePlugin\" didn't set up a resolver"},{"fix":"Run 'npm install dotenv --save-dev'.","cause":"dotenv is not installed but is required by the plugin.","error":"Error: Cannot find module 'dotenv'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}