From 8f322fbacd178017f91d8c5f7de692182666f11e Mon Sep 17 00:00:00 2001 From: Eli Perelman Date: Thu, 2 Mar 2017 09:18:09 -0600 Subject: [PATCH] Why use a chaining API? (#87) --- docs/FAQ.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index b8f28ff..dacd2b8 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -24,3 +24,37 @@ give you the power to confine these changes to a single package. Some of these p between ease of set up and black-boxing the configuration. Once you decide to make a configuration change, you are forced to maintain the entire configuration and its dependencies in perpetuity. We believe Neutrino represents a good balance between ease of set up and future extensibility. + +## Why don't presets use a normal Webpack configuration object instead of the chaining API? + +The Webpack configuration works well when it is embedded into a single project, and it is the only configuration +file to maintain. Once the configuration is no longer co-located with the project, and needs to be extended or +modified across different projects, it becomes very messy to make those modifications. + +For example, let's say that a preset instead used the Webpack object configuration and added an instance of the +`EnvironmentPlugin`: + +```js +config.plugins.push(new webpack.EnvironmentPlugin(['NODE_ENV'])); +``` + +If you wanted to extend this plugin in your own project to add more environment variables, you would most likely +resort to either adding a new instance of the `EnvironmentPlugin` by requiring Webpack yourself, or looping through +Webpack's plugin array, removing the plugin, and re-instantiating it with your own arguments. + +```js +config.plugins = config.plugins.map(plugin => { + if (plugin.constructor.name !== 'EnvironmentPlugin') { + return plugin; + } + + return new webpack.EnvironmentPlugin([...plugin.keys, ...customEnvironmentVariables]); +}); +``` + +This forces a much higher maintenance burden on your project, and this is only a very simple example. Modifying +loaders created from raw Webpack configuration objects can be **much** more unwieldy. + +Using [webpack-chain](https://github.com/mozilla-rpweb/webpack-chain) affords Neutrino the ability to identify and +manipulate parts of the configuration without resorting to object and array manipulation hacks, something not currently +possible when working with raw Webpack configuration data.