webpack-merge - Merge designed for Webpack
webpack-merge provides a merge
function that concatenates arrays and merges objects creating a new object. If functions are encountered, it will execute them, run the results through the algorithm, and then wrap the returned values within a function again.
This behavior is particularly useful in configuring webpack although it has uses beyond it. Whenever you need to merge configuration objects, webpack-merge can come in handy.
There's also a webpack specific merge variant known as merge.smart
that's able to take webpack specifics into account (i.e., it can flatten loader definitions).
Standard Merging
merge(...configuration | [...configuration])
merge
is the core, and the most important idea, of the API. Often this is all you need unless you want further customization.
// Default APIvar output = ; // You can pass an array of objects directly.// This works with all available functions.var output = ;
merge({ customizeArray, customizeObject })(...configuration | [...configuration])
merge
behavior can be customized per field through a curried customization API.
// Customizing array/object behaviorvar output = object1 object2 object3 ...;
For example, if the previous code was invoked with only object1
and object2
with object1
as:
{
foo1: ['object1'],
foo2: ['object1'],
bar1: { object1: {} },
bar2: { object1: {} },
}
and object2
as:
{
foo1: ['object2'],
foo2: ['object2'],
bar1: { object2: {} },
bar2: { object2: {} },
}
then customizeArray
will be invoked for each property of Array
type, i.e:
customizeArray(['object1'], ['object2'], 'foo1');
customizeArray(['object1'], ['object2'], 'foo2');
and customizeObject
will be invoked for each property of Object
type, i.e:
customizeObject({ object1: {} }, { object2: {} }, bar1);
customizeObject({ object1: {} }, { object2: {} }, bar2);
merge.unique(<field>, <fields>, field => field)
const output = plugins: plugins: ; // Output contains only single HotModuleReplacementPlugin now.
Merging with Strategies
merge.strategy({ <field>: '<prepend|append|replace>''})(...configuration | [...configuration])
Given you may want to configure merging behavior per field, there's a strategy variant:
// Merging with a specific merge strategyvar output = mergeobject1 object2 object3 ...;
merge.smartStrategy({ <key>: '<prepend|append|replace>''})(...configuration | [...configuration])
The same idea works with smart merging too (described below in greater detail).
var output = mergeobject1 object2 object3 ...;
Smart Merging
merge.smart(...configuration | [...configuration])
webpack-merge tries to be smart about merging loaders when merge.smart
is used. Loaders with matching tests will be merged into a single loader value.
Note that the logic picks up webpack 2 rules
kind of syntax as well. The examples below have been written in webpack 1 syntax.
package.json
{ "scripts": { "start": "webpack-dev-server", "build": "webpack" }, // ...}
webpack.config.js
var path = ;var merge = ; var TARGET = processenvnpm_lifecycle_event; var common = entry: path ... module: loaders: test: /\.css$/ loaders: 'style' 'css' ; ifTARGET === 'start' moduleexports = ; ifTARGET === 'build' moduleexports = ; ...
Loader string values loader: 'babel'
override each other.
merge;// will become loaders: test: /\.js$/ loader: 'coffee'
Loader array values loaders: ['babel']
will be merged, without duplication.
merge;// will become loaders: test: /\.js$/ // appended because Webpack evaluated these from right to left // this way you can specialize behavior and build the loader chain loaders: 'babel' 'coffee'
Loader array values loaders: ['babel']
can be reordered by including
original loaders.
merge;// will become loaders: test: /\.js$/ // order of second argument is respected loaders: 'react-hot' 'babel'
This also works in reverse - the existing order will be maintained if possible:
merge;// will become loaders: test: /\.css$/ use: loader: 'css-loader' options: myOptions: true loader: 'style-loader' options: someSetting: true
In the case of an order conflict, the second order wins:
merge;// will become loaders: test: /\.css$/ use: loader: 'style-loader' loader: 'css-loader'
Loader query strings loaders: ['babel?plugins[]=object-assign']
will be overridden.
merge;// will become loaders: test: /\.js$/ loaders: 'babel' 'coffee'
Loader arrays in source values will have loader strings merged into them.
merge;// will become loaders: test: /\.js$/ // appended because Webpack evaluated these from right to left! loaders: 'babel' 'coffee'
Loader strings in source values will always override.
merge;// will become loaders: test: /\.js$/ loader: 'coffee'
Multiple Merging
merge.multiple(...configuration | [...configuration])
Sometimes you may need to support multiple targets, webpack-merge will accept an object where each key represents the target configuration. The output becomes an array of configurations where matching keys are merged and non-matching keys are added.
var path = ;var baseConfig = server: target: 'node' output: path: path filename: 'lib.node.js' client: output: path: path filename: 'lib.js' ; // specialized configurationvar production = client: output: path: path filename: '[name].[hash].js' moduleexports = mergemultiplebaseConfig production
Check out SurviveJS - Webpack and React to dig deeper into the topic.
Development
npm i
npm run build
npm run watch
Before contributing, please open an issue where to discuss.
License
webpack-merge is available under MIT. See LICENSE for more details.