Webpack-Builder

currently beta

Let's face it, Webpack is awesome... but configuring it... not so much.

Webpack-Builder is a utility to take the pain away from Webpack configuration by providing a declarative API to interact with.

The idea is to make the API easy enough that you can simply sit down and start typing away at your webpack.config.js file without having to resort to reading documentation; running a boilerplate; or locating saved snippets from somewhere.

Also, webpack-builder will add some convenient plugins to make the user experience better:

• Adds a progress bar that runs alerting you of the current build progress.
• Adds a plugin to cleanup the reporting provided by the default Webpack builds.
• Adds auto-install functionality, which will automatically run npm install on new dependencies added to package.json

Installation

npm install --save-dev webpack-builder

Usage

First, we can configure our basic settings. The main setting to be concerned with here is "outputFolder". This is the path from which all filenames will be relative to. It is equivilent to the webpack setting config.output.path. Typically this is set to your "public" folder.

'use strict';
 
const path = require('path');
const Builder = require('webpack-builder');
 
const builder = new Builder({
  outputFolder: path.join(__dirname, 'public'), // defaults to path.join(process.cwd(), 'public')
});
 
// INSERT FILE HANDLING DEFINITIONS HERE
 
module.exports = builder.toWebpack()

After that we can start adding the setup for certain file types. To add a new babel entry point to our application is as simple as providing the desired build location/name with the source file:

...
 
// INSERT FILE HANDLING DEFINITIONS HERE
builder.babel('js/website.js', path.join(__dirname,'src/website.jsx'))
 
module.exports = builder.toWebpack()

The above line will add in the necessary configuration to deal with es6 files. For this to work however, you will also need to add your .babelrc file to your project root to instruct babel on how to function.

Before it actually runs Webpack, it will first compare its build dependencies with your package.json, and determine if you are missing anything. If you are indeed missing dependencies, it will do one of 2 things:

• If your autoInstall configuration is true (default), it will automatically update your package.json with the new dependencies, and run npm install
• Otherwise it will simply alert you of the missing dependencies, as well as provide you a one-liner to install all of the dependencies you need.

Chaining

You can also chain options for more complicated loaders, just remember that ordering is important:

builder.sass().postcss()

Configuration

The Builder constructor also accepts configuration parameters:

//defaults
const builder = new Builder({
  outputFolder: path.join(process.cwd(), 'public'),
  friendlyErrors: true,
  progressBar: true,
  autoInstall: true,
  debug: false,
});

You can also add additional configuration options to each loader chain:

builder.babel('js/website.js', path.join(__dirname,'src/website.jsx'), {
    include: path.join(__dirname, 'src'),
    exclude: /node_modules/,
    useJsx: true,
})

Note that the config is shared across all chained loaders, so passing the same config in a later loader in the middle of a chain will overwrite the previous.

Environment-specific Configuration

webpack-builder comes with a utility to get the name of the currently executing npm script. For instance if you have a package.json such as:

...
"scripts": {
  "dev": "webpack -w",
  "start": "webpack -w",
  "build": "webpack"
}

you could update your webpack.config.js to add the following:

...
if(builder.npmScriptName() === 'build') {
  builder.production();
}
else {
  builder.development();
}
...

With that example, running npm start or npm run dev would result in the development settings being applied. However running npm run build would yield in a production-optimized build.

Under the hood webpack-builder is just doing:

npmScriptName() {
  return process.env.npm_lifecycle_event
}

Output

Thanks to friendly-errors-webpack-plugin and progress-bar-webpack-plugin we have a sanitized, and useful output.

Build Success

Build Progress

Notice how it specifies which environment it is currently building for.

Build Error

Debugging

If you are having trouble with your configuration you can add the debug parameter to your configuration options. This will dump the resulting webpack.config file in pretty-printed JSON.

const builder = new Builder({
  outputFolder: path.join(__dirname, 'public'),
  debug: true,
});

Examples

See the examples directory for a few usage examples.