webpack-chain
Use a chaining API to generate and simplify the modification of Webpack 2 configurations.
This README corresponds to v3 of webpack-chain.
Introduction
Webpack's core configuration is based on creating and modifying a potentially unwieldy JavaScript object. While this is OK for configurations on individual projects, trying to share these objects across projects and make subsequent modifications gets messy, as you need to have a deep understanding of the underlying object structure to make those changes.
webpack-chain
attempts to improve this process by providing a chainable or
fluent API for creating and modifying webpack configurations. Key portions
of the API can be referenced by user-specified names, which helps to
standardize how to modify a configuration across projects.
This is easier explained through the examples following.
Contributing
We welcome any contributor. Just fork and clone, make changes, and send a pull request.
Installation
webpack-chain
requires Node.js v6.9 and higher. webpack-chain
also
only creates configuration objects designed for use in Webpack 2.
You may install this package using either Yarn or npm (choose one):
Yarn
yarn add --dev webpack-chain
npm
npm install --save-dev webpack-chain
Getting Started
Once you have webpack-chain
installed, you can start creating a
Webpack configuration. For this guide, our example base configuration will
be webpack.config.js
in the root of our project directory.
// Require the webpack-chain module. This module exports a single// constructor function for creating a configuration API.const Config = ; // Instantiate the configuration with a new APIconst config = ; // Make configuration changes using the chain API.// Every API call tracks a change to the stored configuration. // Interact with entry pointsconfig // Modify output settings output filename'[name].bundle.js'; // Create named rules which can be modified laterconfigmodule include // Even create named uses (loaders) for later modification options rules: semi: 'off' ; configmodule include options presets: 'babel-preset-es2015' modules: false ; // Create named plugins, too!config ; // Export the completed configuration object to be consumed by webpackmoduleexports = config;
Having shared configurations is also simple. Just export the configuration
and call .toConfig()
prior to passing to Webpack.
// webpack.core.jsconst Config = ;const config = ; // Make configuration shared across targets// ... moduleexports = config; // webpack.dev.jsconst config = ; // Dev-specific configuration// ...moduleexports = config; // webpack.prod.jsconst config = ; // Production-specific configuration// ...moduleexports = config;
ChainedMap
One of the core API interfaces in webpack-chain is a ChainedMap
. A ChainedMap
operates
similar to a JavaScript Map, with some conveniences for chaining and generating configuration.
If a property is marked as being a ChainedMap
, it will have an API and methods as described below:
Unless stated otherwise, these methods will return the ChainedMap
, allowing you to chain these methods.
// Remove all entries from a Map.
// Remove a single entry from a Map given its key.// key: *deletekey
// Fetch the value from a Map located at the corresponding key.// key: *// returns: value
// Set a value on the Map stored at the `key` location.// key: *// value: *
// Returns `true` or `false` based on whether a Map as has a value set at a particular key.// key: *// returns: Boolean
// Returns an array of all the values stored in the Map.// returns: Array
// Returns an object of all the entries in the backing Map// where the key is the object property, and the value// corresponding to the key. Will return `undefined` if the backing // Map is empty.// returns: Object, undefined if empty
// Provide an object which maps its properties and values // into the backing Map as keys and values.// obj: Object
ChainedSet
Another of the core API interfaces in webpack-chain is a ChainedSet
. A ChainedSet
operates
similar to a JavaScript Set, with some conveniences for chaining and generating configuration.
If a property is marked as being a ChainedSet
, it will have an API and methods as described below:
Unless stated otherwise, these methods will return the ChainedSet
, allowing you to chain these methods.
// Add/append a value to the end of a Set.// value: *
// Add a value to the beginning of a Set.// value: *
// Remove all values from a Set.
// Remove a specific value from a Set.// value: *deletevalue
// Returns `true` or `false` based on whether or not the// backing Set contains the specified value.// value: *// returns: Boolean
// Returns an array of values contained in the backing Set.// returns: Array
// Concatenates the given array to the end of the backing Set.// arr: Array
Shorthand methods
A number of shorthand methods exist for setting a value on a ChainedMap
with the same key as the shorthand method name.
For example, devServer.hot
is a shorthand method, so it can be used as:
// A shorthand method for setting a value on a ChainedMapdevServer; // This would be equivalent to:devServer;
A shorthand method is chainable, so calling it will return the original instance, allowing you to continue to chain.
Config
Create a new configuration object.
const Config = ; const config = ;
Moving to deeper points in the API will change the context of what you
are modifying. You can move back to the higher context by either referencing
the top-level config
again, or by calling .end()
to move up one level.
If you are familiar with jQuery, .end()
works similarly. All API calls
will return the API instance at the current context unless otherwise
specified. This is so you may chain API calls continuously if desired.
For details on the specific values that are valid for all shorthand and low-level methods, please refer to their corresponding name in the Webpack docs hierarchy.
Config : ChainedMap
Config shorthand methods
config profileprofile targettarget
Config entryPoints
// Backed at config.entryPoints : ChainedMapconfig : ChainedSet config config clear // Using low-level config.entryPoints: configentryPoints configentryPoints clear
Config output: shorthand methods
configoutput : ChainedMap configoutput filenamefilename
Config resolve: shorthand methods
configresolve : ChainedMap configresolve
Config resolve alias
configresolvealias : ChainedMap configresolvealias clear
Config resolve modules
configresolvemodules : ChainedSet configresolvemodules clear
Config resolve aliasFields
configresolvealiasFields : ChainedSet configresolvealiasFields clear
Config resolve descriptionFields
configresolvedescriptionFields : ChainedSet configresolvedescriptionFields clear
Config resolve extensions
configresolveextensions : ChainedSet configresolveextensions clear
Config resolve mainFields
configresolvemainFields : ChainedSet configresolvemainFields clear
Config resolve mainFiles
configresolvemainFiles : ChainedSet configresolvemainFiles clear
Config resolveLoader
configresolveLoader : ChainedMap
Config resolveLoader extensions
configresolveLoaderextensions : ChainedSet configresolveLoaderextensions clear
Config resolveLoader modules
configresolveLoadermodules : ChainedSet configresolveLoadermodules clear
Config resolveLoader moduleExtensions
configresolveLoadermoduleExtensions : ChainedSet configresolveLoadermoduleExtensions clear
Config resolveLoader packageMains
configresolveLoaderpackageMains : ChainedSet configresolveLoaderpackageMains clear
Config performance: shorthand methods
configperformance : ChainedMap configperformance
Config plugins
// Backed at config.pluginsconfig : ChainedMap
Config plugins: adding
NOTE: Do not use new
to create the plugin, as this will be done for you.
config // Examplesconfig ; config ;
Config plugins: modify arguments
config // Exampleconfig ;
Config plugins: modify instantiation
config ;
Config resolve plugins
// Backed at config.pluginsconfigresolve : ChainedMap
Config resolve plugins: adding
NOTE: Do not use new
to create the plugin, as this will be done for you.
configresolve
Config plugins: modify arguments
configresolve
Config plugins: modify instantiation
configresolve
Config node
confignode : ChainedMap confignode ;
Config devServer
configdevServer : ChainedMap
Config devServer: shorthand methods
configdevServer filenamefilename headersheaders hosthost portport
Config module
configmodule : ChainedMap
Config module rules: shorthand methods
configmodulerules : ChainedMap configmodule
Config module rules uses (loaders): creating
configmodulerules{}uses : ChainedMap configmodule optionsoptions // Example configmodule options presets: 'babel-preset-es2015' ;
Config module rules uses (loaders): modifying options
configmodule // Example configmodule ;
Merging Config
webpack-chain supports merging in an object to the configuration instance which matches a layout similar to how the webpack-chain schema is laid out. Note that this is not a Webpack configuration object, but you may transform a Webpack configuration object before providing it to webpack-chain to match its layout.
config; config // "source-map"
config