{"id":19450,"library":"dotenv-webpack","title":"dotenv-webpack","description":"A secure webpack plugin that wraps dotenv and Webpack.DefinePlugin to expose only explicitly referenced process.env variables in your bundle. Current version 9.0.0 (2026-03-07) supports webpack 4/5 and Node >=18.18.0. Unlike raw dotenv, it safely reduces leakage of sensitive keys by only including variables actually used in code. Compatible with rspack since v8.1.0. Breaking change in v9: package exports directly from src/index.js, no dist/ wrappers. Release cadence is irregular, with major versions every 1-2 years.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/mrsteele/dotenv-webpack","tags":["javascript","dotenv","env","safe","environment","dotenv-safe","variables","process","process.env","typescript"],"install":[{"cmd":"npm install dotenv-webpack","lang":"bash","label":"npm"},{"cmd":"yarn add dotenv-webpack","lang":"bash","label":"yarn"},{"cmd":"pnpm add dotenv-webpack","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin functionality","package":"webpack","optional":false},{"reason":"core dependency for .env file parsing","package":"dotenv","optional":false}],"imports":[{"note":"Package is ESM-only since v9. CommonJS require will fail with newer Node versions.","wrong":"const Dotenv = require('dotenv-webpack');","symbol":"Dotenv","correct":"import Dotenv from 'dotenv-webpack';"},{"note":"In CJS compatible versions (v8 and below), default import is via require. Named import for Dotenv does not exist.","wrong":"const { Dotenv } = require('dotenv-webpack');","symbol":"Dotenv","correct":"const Dotenv = require('dotenv-webpack');"},{"note":"Only default export is provided. Named export is a common mistake.","wrong":"import { Dotenv } from 'dotenv-webpack';","symbol":"Dotenv","correct":"import Dotenv from 'dotenv-webpack';"}],"quickstart":{"code":"// webpack.config.js\nimport Dotenv from 'dotenv-webpack';\n\nexport default {\n  plugins: [\n    new Dotenv()\n  ]\n};\n\n// .env\nDB_HOST=127.0.0.1\nDB_PASS=foobar\nS3_API=mysecretkey\n\n// file.js\nconsole.log(process.env.DB_HOST); // '127.0.0.1'\n// DB_PASS and S3_API are NOT in bundle because not referenced\n","lang":"typescript","description":"Shows basic setup with ESM import, .env file, and secure variable usage."},"warnings":[{"fix":"Update import to default ESM import; if using older Node or custom resolver, ensure module resolution handles src/.","message":"Since v9.0.0, package exports directly from src/index.js, removing dist/index.js wrappers. This may break builds relying on the dist path.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Review config: if you relied on separate defaults, explicitly set options to mimic old behavior.","message":"v8.0.0 changed the default behavior of `path`, `defaults` and `safe` options to all look at the `path` by default. Previously they had separate defaults.","severity":"breaking","affected_versions":">=8.0.0 <9.0.0"},{"fix":"Always reference variables as process.env.VAR_NAME directly. Do not destructure.","message":"Destructuring process.env variables (e.g., const { DB_HOST } = process.env) will not be replaced by the plugin due to webpack.DefinePlugin limitations.","severity":"gotcha","affected_versions":"*"},{"fix":"If using `prefix`, ensure all process.env references are handled, or manually handle missing env vars.","message":"When `prefix` option is set, automatic stubbing of missing process.env references (replacing with 'MISSING_ENV_VAR') is disabled. If your code or dependencies use process.env without referencing a variable, it will break.","severity":"gotcha","affected_versions":">=7.1.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm install webpack@5 --save-dev' or ensure webpack is in dependencies.","cause":"Webpack not installed or incompatible version (need webpack 4 or 5).","error":"TypeError: Cannot read properties of undefined (reading 'DefinePlugin')"},{"fix":"Switch to import syntax or downgrade to v8.1.1 if you cannot use ESM.","cause":"Using CommonJS require with v9 ESM-only package in a non-ESM project.","error":"Error: Module parse failed: Unexpected token (1:2)\nYou may need an appropriate loader to handle this file type."},{"fix":"Run 'npm install dotenv' or remove --no-optional flag.","cause":"dotenv is not installed as a dependency (it should be installed automatically, but might be missing if using --no-optional).","error":"WARNING in (webpack)/node_modules/dotenv-webpack/src/index.js\nModule not found: Error: Can't resolve 'dotenv'"},{"fix":"Either set `ignoreStub: false` (default) or add 'process/browser' polyfill in webpack config.","cause":"In browser environments (webpack 5+), process is not polyfilled. dotenv-webpack normally stubs missing process.env but may fail if `ignoreStub` is set or `prefix` is used.","error":"process is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}