webpack-merge

6.0.1 verified Sat Apr 25 auth: no javascript

A specialized merge library designed for webpack configuration objects. Version 6.0.1 is the current stable release, requiring Node >=18.0.0. Unlike generic merge utilities (e.g., Lodash.merge), it concatenates arrays, merges objects, and executes functions before merging—critical for webpack's plugin arrays and nested rules. Ships TypeScript types. Maintained actively, with minor/patch releases every few months.

Common errors

error Cannot find module 'webpack-merge' ↓

cause Package not installed or incorrect import path in older versions.

fix

npm install webpack-merge@6.0.1 and use correct import syntax.

error merge is not a function ↓

cause CommonJS require without destructuring: const merge = require('webpack-merge') returns an object, not function.

fix

Use const { merge } = require('webpack-merge') or import { merge } from 'webpack-merge'.

error TypeError: mergeWithCustomize is not a function ↓

cause Importing as default when it's a named export.

fix

Import as named export: import { mergeWithCustomize } from 'webpack-merge'.

Warnings

breaking In v6, Node.js <18 is no longer supported. ↓

fix Upgrade Node.js to >=18.0.0 or stick with v5.

breaking Default merge behavior changed: arrays are concatenated, not replaced. ↓

fix If you need replacement, use mergeWithCustomize with a customArray function that returns b instead of concatenating.

deprecated merge.smart and merge.strategy removed in v5. ↓

fix Use mergeWithCustomize or merge() directly.

gotcha Functions are executed before merging; if you pass a function returning a config, it will be called and merged. ↓

fix Wrap function-returning configs in an async wrapper only if you need async behavior; note Promises are not supported.

gotcha Objects are merged deeply; nested objects are not replaced by default. ↓

fix Use mergeWithCustomize with customizeObject if you want replacement semantics.

Install

npm install webpack-merge

yarn add webpack-merge

pnpm add webpack-merge

Imports

merge
```
import { merge } from 'webpack-merge'
```
ESM default import pattern. Use named import for 'merge'.
merge
wrong
```
const merge = require('webpack-merge')
```
correct
```
const { merge } = require('webpack-merge')
```
CommonJS requires destructuring; default export is an object with merge as a property.
mergeWithCustomize
```
import { mergeWithCustomize } from 'webpack-merge'
```
Named export for custom merging behavior.

customizeArray

import { customizeArray } from 'webpack-merge'

Named export; not a default.

Quickstart

Shows merging a common webpack config with environment-specific overrides using merge().

const { merge } = require('webpack-merge');

const common = {
  entry: './src/index.js',
  output: { filename: 'bundle.js' }
};

const dev = {
  mode: 'development',
  devtool: 'inline-source-map'
};

const prod = {
  mode: 'production',
  optimization: { minimize: true }
};

const env = process.env.NODE_ENV || 'development';
const config = merge(common, env === 'development' ? dev : prod);

module.exports = config;