Webpack

Common errors

• Module not found: Error: Can't resolve 'some-module' in 'path/to/source'

  cause Webpack cannot find the specified module, usually because a required loader is missing, the import path is incorrect, or the dependency is not installed.
  fix Install the missing loader (e.g., `npm install --save-dev some-loader`), correct the module's import path, or install the dependency (`npm install some-module`).

• Error: A plugin must be an instance of WebpackPluginInstance

  cause You are passing a plugin class definition (e.g., `MyPlugin`) directly to the `plugins` array in `webpack.config.js` instead of an instantiated object.
  fix Instantiate your plugin by calling its constructor: `plugins: [new MyPlugin({ /* options */ })]`.

• webpack command not found

  cause The `webpack` executable is not in your system's PATH, typically because it's installed as a local `devDependency` and not globally, or `npx` (which resolves local binaries) is not being used.
  fix Run `npx webpack` to execute the locally installed version, or add a script to `package.json` (e.g., `"build": "webpack"`) and run with `npm run build` or `yarn build`.

• ERR_REQUIRE_ESM

  cause Occurs when a CommonJS module attempts to `require()` an ES Module that only provides an ESM export, especially in newer Node.js environments or when there's a mismatch in module resolution configuration.
  fix Ensure your `webpack.config.js` and `package.json` are correctly configured for your target module system (ESM or CJS). You might need to adjust `output.module` or use dynamic `import()` within CommonJS contexts for ESM modules.

Warnings

• breaking Since webpack 4, the `mode` option ('development', 'production', or 'none') is crucial. Not defining it will result in a warning and a fallback to 'production' mode, which might apply unexpected optimizations or skip helpful development features.
  Fix: Explicitly add `mode: 'development'` or `mode: 'production'` to your `webpack.config.js`.
• gotcha Webpack and its loaders/plugins are development dependencies. They should always be installed with `--save-dev` (or `-D`) because they are build tools and not required at runtime in your production application.
  Fix: Ensure `webpack`, `webpack-cli`, and any loaders/plugins are listed under `devDependencies` in your `package.json`. If you previously installed globally, consider removing the global install and using `npx` for local binaries.
• gotcha Webpack v5 removed automatic polyfills for Node.js built-ins (like `process`, `Buffer`, `crypto`). If your browser-targeted code relies on these, you might encounter `ReferenceError: process is not defined` or similar.
  Fix: Use browser-compatible alternatives where possible. If Node.js built-ins are unavoidable, explicitly polyfill them using webpack's `ProvidePlugin` or configure `resolve.fallback` for specific modules.
• gotcha When using `experimental.futureDefaults`, asset modules (`type: 'asset'`) are only marked as side-effect-free. This can lead to unexpected tree-shaking of asset files if you rely on them having side-effects (e.g., an `import './style.css'` for global styling).
  Fix: Review your `sideEffects` configuration in `package.json` to ensure asset imports are correctly handled. If unexpected tree-shaking occurs, consider disabling `experimental.futureDefaults` or explicitly marking asset files as having side-effects if necessary.

Install

• npm install webpack npm
• yarn add webpack yarn
• pnpm add webpack pnpm

Imports

• webpack
  wrong:

  const webpack = require('webpack');

  correct:

  import webpack from 'webpack';

  While CommonJS `require` is still supported in Node.js environments, `import` is the preferred syntax for modern TypeScript and ES module setups when using webpack's Node.js API.

Quickstart

This quickstart demonstrates how to set up a basic webpack configuration to bundle a JavaScript file and an imported CSS file into `dist/bundle.js`. To run, save the config, create the `src` files, then execute `npm install --save-dev webpack webpack-cli style-loader css-loader` followed by `npx webpack`.

/* webpack.config.js */
const path = require('path');

module.exports = {
  mode: 'development', // 'production' or 'none'
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  // Add basic loader for CSS as an example
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
};

/* src/index.js */
import './style.css';
console.log('Hello from Webpack!');

/* src/style.css */
body { font-family: sans-serif; }