feat: built in env files support

.gitignore

@@ -64,5 +64,7 @@ test/**/**/**/bin/
 test/**/**/binary/**
 test/**/dist
 test/**/**/dist
+test/**/**/dist1
+test/**/**/dist2
 test/**/**/**/dist
 test/**/stats.json

OPTIONS.md

@@ -706,6 +706,7 @@ Options:
   --performance-max-entrypoint-size <value>                                          Total size of an entry point (in bytes).
   --profile                                                                          Capture timing information for each module.
   --no-profile                                                                       Negative 'profile' option.
+  --read-dot-env                                                                     Read environment variables from dotenv files
   --records-input-path <value>                                                       Store compiler state to a json file.
   --no-records-input-path                                                            Negative 'records-input-path' option.
   --records-output-path <value>                                                      Load compiler state from a json file.

packages/README.md

@@ -18,6 +18,7 @@ This folder is the collection of those packages.
 3. [info](https://github.com/webpack/webpack-cli/tree/master/packages/info)
 4. [serve](https://github.com/webpack/webpack-cli/tree/master/packages/serve)
 5. [webpack-cli](https://github.com/webpack/webpack-cli/tree/master/packages/webpack-cli)
+6. [dotenv-webpack-plugin](https://github.com/webpack/webpack-cli/tree/master/packages/dotenv-webpack-plugin)
 
 ## Generic Installation
 

packages/dotenv-webpack-plugin/README.md

@@ -0,0 +1,91 @@
+# Dotenv Webpack Plugin
+
+`dotenv-webpack-plugin` is a webpack plugin that enables consumers to load environment variables from dotenv files. This plugin simplifies the process of managing environment-specific configurations in your webpack projects.
+
+## Features
+
+- Loads environment variables from dotenv files
+- Provides a convenient way to manage environment-specific configurations
+- Fully configurable via an options API
+
+## Installation
+
+Install `dotenv-webpack-plugin` using npm:
+
+```bash
+npm install dotenv-webpack-plugin --save-dev
+```
+
+or using yarn:
+
+```bash
+yarn add dotenv-webpack-plugin --dev
+```
+
+or using pnpm:
+
+```bash
+pnpm add dotenv-webpack-plugin --save-dev
+```
+
+## Usage
+
+To use `dotenv-webpack-plugin`, follow these steps:
+
+1.  Create a `.env` file in the root directory of your project. Add each environment variable on a new lines in the form of `PUBLIC_NAME=VALUE`. By default only variables that are prefixed with `PUBLIC_` will be exposed to webpack. The prefix can be changed by passing the `envVarPrefix` option to the plugin.
+
+1.  Import `dotenv-webpack-plugin` in your webpack configuration file:
+
+    ```javascript
+    const DotenvWebpackPlugin = require("dotenv-webpack-plugin");
+    ```
+
+1.  Add an instance of DotenvWebpackPlugin to your webpack plugins:
+
+    ```javascript
+    module.exports = {
+      // Your webpack configuration options...
+      plugins: [new DotenvWebpackPlugin()],
+    };
+    ```
+
+## Configuration Options
+
+DotenvWebpackPlugin accepts the following configuration options:
+
+1. `envFiles`: An array of dotenv files to load. By default, DotenvWebpackPlugin will look for the following files in the root directory of your project:
+
+   - `.env.[mode].local`
+   - `.env.local`
+   - `.env.[mode]`
+   - `.env`
+   - `.env.example`
+
+   The `[mode]` placeholder will be replaced with the current webpack mode. For example, if the current webpack mode is `development`, DotenvWebpackPlugin will look for the following files:
+
+   - `.env.development.local`
+   - `.env.local`
+   - `.env.development`
+   - `.env`
+   - `.env.example`
+
+   If the same variable is defined in multiple files, the value from the file with the highest precedence will be used. The precedence order is same as the order of files listed above.
+
+   While passing an array of dotenv files, the path towards the right of the array will have the highest precedence. For example, if you pass `["./.env", "./.env.local"]`, the value from `.env.local` will be used if the same variable is defined in both files.
+
+1. `envVarPrefix`: The prefix to use when loading environment variables. By default, DotenvWebpackPlugin will look for variables prefixed with `PUBLIC_`.
+
+1. `prefixes`: An array of prefixes to prepend to the names of environment variables. By default, DotenvWebpackPlugin will prepend `process.env.` and `import.meta.env.` to the names of environment variables.
+
+1. `allowEmptyValues`: A boolean value indicating whether to allow empty values. By default this value is set to `false`, DotenvWebpackPlugin will throw an error if an environment variable is defined without a value.
+
+You can pass these options when creating an instance of DotenvWebpackPlugin:
+
+```javascript
+new DotenvWebpackPlugin({
+  envFiles: ["./.env", "./.env.local"],
+  prefixes: ["process.env.", "import.meta.env."],
+  envVarPrefix: "PUBLIC_",
+  allowEmptyValues: false,
+});
+```

packages/dotenv-webpack-plugin/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "dotenv-webpack-plugin",
+  "version": "1.0.0",
+  "description": "A webpack plugin to support env files",
+  "main": "src/index.js",
+  "types": "src/types.d.ts",
+  "repository": "https://github.com/webpack/webpack-cli",
+  "license": "MIT",
+  "private": true,
+  "dependencies": {
+    "dotenv": "^16.0.3",
+    "dotenv-expand": "^10.0.0",
+    "schema-utils": "^4.0.1"
+  },
+  "peerDependencies": {
+    "webpack": "5.x.x"
+  },
+  "devDependencies": {
+    "webpack": "^5.81.0"
+  }
+}

packages/dotenv-webpack-plugin/src/index.js

@@ -0,0 +1,212 @@
+const dotenv = require("dotenv");
+const dotenvExpand = require("dotenv-expand");
+const { DefinePlugin, WebpackError } = require("webpack");
+const { validate } = require("schema-utils");
+const schema = require("./options.json");
+
+/** @typedef {import("./types").Config} Config */
+/** @typedef {import("schema-utils/declarations/validate").Schema} Schema */
+/** @typedef {import("webpack").Compiler} Compiler */
+/** @typedef {import("webpack").Compilation} Compilation */
+
+class DotenvWebpackPlugin {
+  /**
+   * Dotenv Webpack Plugin
+   * @param {Config} options - Configuration options
+   */
+  constructor(options = {}) {
+    validate(/** @type {Schema} */ (schema), options || {}, {
+      name: "DotenvWebpackPlugin",
+      baseDataPath: "options",
+    });
+
+    const currentDirectory = process.cwd();
+
+    this.defaultFileList = [
+      `${currentDirectory}/.env.example`, // loaded in all cases
+      `${currentDirectory}/.env`, // loaded in all cases
+      `${currentDirectory}/.env.[mode]`, // only loaded in specified mode
+      `${currentDirectory}/.env.local`, // loaded in all cases, ignored by git
+      `${currentDirectory}/.env.[mode].local`, // only loaded in specified mode, ignored by git
+    ];
+
+    const {
+      // priority is in ascending order
+      // files at the end of the array have higher priority
+      envFiles = this.defaultFileList,
+      prefixes = ["process.env.", "import.meta.env."],
+      envVarPrefix = "PUBLIC_",
+      allowEmptyValues = false,
+    } = options;
+
+    this.options = {
+      envFiles,
+      prefixes,
+      envVarPrefix,
+      allowEmptyValues,
+    };
+
+    this.errors = [];
+  }
+
+  /**
+   * Default file list and the options file list are updated with the
+   * value of the mode if [mode] placeholder is used
+   * @param {String} mode - Webpack mode
+   */
+  updateFileListWithMode(mode) {
+    this.options.envFiles = this.options.envFiles.map((environmentFile) =>
+      environmentFile.replace(/\[mode\]/g, mode),
+    );
+    this.defaultFileList = this.defaultFileList.map((environmentFile) =>
+      environmentFile.replace(/\[mode\]/g, mode),
+    );
+  }
+
+  /**
+   * Read file from path and parse it
+   * @param {Compiler} compiler - Webpack compiler
+   * @param {string} environmentFile - Path to environment file
+   */
+  readFile(compiler, environmentFile) {
+    return new Promise((resolve, reject) => {
+      const fs = compiler.inputFileSystem;
+
+      fs.readFile(environmentFile, (err, environmentFileContents) => {
+        if (err) {
+          if (!this.defaultFileList.includes(environmentFile)) {
+            this.collectError(`Could not read ${environmentFile}`);
+            return reject(err);
+          } else {
+            return resolve();
+          }
+        }
+
+        const parsedEnvVariables = dotenv.parse(environmentFileContents);
+
+        resolve(parsedEnvVariables);
+      });
+    });
+  }
+
+  filterVariables(envVariables) {
+    const filteredEnvVariables = {};
+
+    for (const [key, value] of Object.entries(envVariables)) {
+      // only add variables starting with the provided prefix
+      if (key.startsWith(this.options.envVarPrefix)) {
+        filteredEnvVariables[key] = value;
+      }
+    }
+
+    return filteredEnvVariables;
+  }
+
+  assignPrefixes(envVariables) {
+    const prefixedEnvVariables = {};
+
+    for (const [key, value] of Object.entries(envVariables)) {
+      for (let index = 0; index < this.options.prefixes.length; index++) {
+        const prefix = this.options.prefixes[index];
+        prefixedEnvVariables[`${prefix}${key}`] = value;
+      }
+    }
+
+    return prefixedEnvVariables;
+  }
+
+  /**
+   * Throw collected errors to fail the build
+   * @param {Compilation} compilation - Webpack compilation
+   */
+  throwErrors(compilation) {
+    const errors = this.errors.map((error) => {
+      const webpackError = new WebpackError(error);
+      webpackError.name = "DotenvWebpackPluginError";
+      return webpackError;
+    });
+    compilation.errors.push(...errors);
+  }
+
+  collectError(errorMessage) {
+    this.errors.push(errorMessage);
+  }
+
+  /**
+   * Get list of empty values
+   * @param {Object} envVariables - Environment variables
+   * @returns {Array} - List of empty values
+   */
+  getEmptyValues(envVariables) {
+    const emptyValues = [];
+
+    for (const [key, value] of Object.entries(envVariables)) {
+      if (value === "") {
+        emptyValues.push(key);
+      }
+    }
+
+    return emptyValues;
+  }
+
+  /**
+   * Webpack apply hook
+   * @param {Compiler} compiler - Webpack compiler
+   * @returns {void}
+   */
+  apply(compiler) {
+    const mode = compiler.options.mode || "production";
+    this.updateFileListWithMode(mode);
+
+    compiler.hooks.beforeRun.tapPromise("DotenvWebpackPlugin", (compiler) => {
+      compiler.hooks.compilation.tap("DotenvWebpackPlugin", (compilation) => {
+        compilation.buildDependencies.addAll(this.options.envFiles);
+        if (this.errors.length > 0) {
+          this.throwErrors(compilation);
+        }
+      });
+
+      return Promise.all(
+        this.options.envFiles.map((environmentFile) => this.readFile(compiler, environmentFile)),
+      )
+        .then((valuesList) => {
+          const envVariables = {};
+
+          valuesList.forEach((values) => {
+            if (values) {
+              Object.entries(values).forEach(([key, value]) => {
+                envVariables[key] = value;
+              });
+            }
+          });
+
+          const filteredEnvVariables = this.filterVariables(envVariables);
+
+          const emptyValues = this.getEmptyValues(filteredEnvVariables);
+
+          if (!this.options.allowEmptyValues && emptyValues.length > 0) {
+            this.collectError(
+              `Environment variables cannot have an empty value. The following variables are empty: ${emptyValues.join(
+                ", ",
+              )}`,
+            );
+            return;
+          }
+
+          const prefixedEnvVariables = this.assignPrefixes(filteredEnvVariables);
+
+          // expand environment vars
+          const expandedEnvVariables = dotenvExpand.expand({
+            parsed: prefixedEnvVariables,
+            // don't write to process.env
+            ignoreProcessEnv: true,
+          }).parsed;
+
+          new DefinePlugin(expandedEnvVariables).apply(compiler);
+        })
+        .catch(() => {});
+    });
+  }
+}
+
+module.exports = DotenvWebpackPlugin;

packages/dotenv-webpack-plugin/src/options.json

@@ -0,0 +1,30 @@
+{
+  "definitions": {},
+  "title": "DotenvWebpackPlugin",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "envFiles": {
+      "description": "The paths to the .env files to load",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "prefixes": {
+      "description": "The prefixes to prepend to the environment variables",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "envVarPrefix": {
+      "description": "The prefix to filter environment variables by",
+      "type": "string"
+    },
+    "allowEmptyValues": {
+      "description": "Whether to allow empty values for environment variables",
+      "type": "boolean"
+    }
+  }
+}

packages/dotenv-webpack-plugin/src/types.d.ts

@@ -0,0 +1,6 @@
+export type Config = {
+  envFiles?: string[];
+  prefixes?: string[];
+  envVarPrefix?: string;
+  allowEmptyValues?: boolean;
+};

packages/webpack-cli/README.md

@@ -84,6 +84,7 @@ Options:
   -m, --merge                                      Merge two or more configurations using 'webpack-merge'.
   --disable-interpret                              Disable interpret for loading the config file.
   --env <value...>                                 Environment passed to the configuration when it is a function.
+  --read-dot-env                                   Read environment variables from dotenv files
   --node-env <value>                               Sets process.env.NODE_ENV to the specified value.
   --define-process-env-node-env <value>            Sets process.env.NODE_ENV to the specified value. (Currently an alias for `--node-env`)
   --analyze                                        It invokes webpack-bundle-analyzer plugin to get bundle information.