DEPRECATED in favour of webpack-build

webpack-wrapper

A wrapper library which provides a variety of optimisations and utilities intended to assist with integrating webpack into a build process.

Features

• Supports multiple concurrent compilers
• Uses a persistent caching layer to reduce build times
• Provides a simple hook to extend a server for HMR support
• Provides config hooks to ensure that your config files reflect the current environment
• Provides build functions to add typical dev/hmr/prod features to your config files
• Pre-processes compilation output so that it can be serialized and efficiently passed between processes
• Provides a helper to redirect the compiler's output to a particular directory
• Provides watchers to detect changes to your config files

Documentation

• Installation
• Basic usage
• Configuration
• Caching
• Builds
• HMR
• Colophon

Installation

npm install webpack-wrapper

Basic usage

var webpack = require('webpack-wrapper');

webpack({config: '/path/to/webpack.config.js'}), function(err, stats) {
  // Besides the usual stats data produced by webpack, the wrapper adds 
  // some extra props...
  
  // The config object generated by webpack
  stats.webpackConfig
  
  // An object mapping asset names to the full path of the generated asset
  stats.pathsToAssets
  
  // An object mapping asset names to the full url of the generated asset.
  // Requires the `staticRoot` and `staticUrl` settings to be defined
  stats.urlsToAssets

  // An array of rendered <script> elements pointing to the JS assets
  stats.rendered.scripts

  // An array of rendered <link> elements pointing to the CSS assets
  stats.rendered.styleSheets
});

Configuration

var webpack = require('webpack-wrapper');

webpack({

  // An absolute path to a config file
  config: '/path/to/webpack.config.js',
  
  // The following options are the default values...
  
  // Indicates that webpack should watch the source files for changes 
  // and rebuild in the background
  watch: false,
  
  // An absolute path to a file that will be used to store cached data
  cacheFile: null,

  // The cache key used to distinguish the current request's compilation.
  // If not defined, it is set to `opts.config + '__' + opts.hash`
  cacheKey: null,

  // A hash value used to distinguish requests, cached values, and hmr connections. 
  // If not defined, the wrapper serializes the options provided and generates a
  // md5 hash
  hash: null,

  // A string denoting the build to apply to the config file
  build: null,

  // If true, applies the `hmr` build to the config file. The build injects code to
  // connect to `opts.hmrRoot` and handle hot module replacement
  hmr: false

  // The base address that hot module replacement requests should be sent
  // to. Example: 'http://127.0.0.1:8000'
  hmrRoot: null,

  // An override for the config's `output.path` property
  outputPath: null,
  
  // An absolute path to the root directory of your static assets,
  // used to calculate `stats.urlsToAssets`
  staticRoot: null,
  
  // The url that your static assets are served from, used to calculate 
  // `stats.urlsToAssets` and configure HMR support
  staticUrl: null,

  // Indicates that the config file should be watched for changes.
  // Any changes will cause webpack to completely rebuild the bundle
  // on the next request. Note: this relies on hacks to circumvent Node's
  // module cache and should be considered purely experimental
  watchConfig: false,
  
  // The delay between the detection of a change in your source files and 
  // the start of a watcher's rebuild process
  aggregateTimeout: 200,
  
  // Indicates if the watcher should poll for changes, rather than 
  // relying on the OS for notifications
  poll: undefined,
  
  // The maximum time that compilation output will be cached for
  cacheTTL: 1000 * 60 * 60 * 24 * 30, // 30 days
  
  // The path on `opts.hmrRoot` that socket connections are made to
  hmrPath: '/__webpack_hmr__',

  // The socket.io namespace that is used by the generated assets. If not
  // defined, it is set to `'/' + opts.hash`
  hmrNamespace: null,
  
  // A console-like object which is written to when the wrapper's state
  // changes, mostly of use for debugging. To suppress all output, set 
  // it to `null`
  logger: console
  
}, function(err, stats) {
  // ...
});

Caching

The wrapper uses a mixture of file and memory caches to improve build times. Specifying the cacheFile option will allow the wrapper to persist the cache to disk, which can boost build times.

When a request comes in and the cache has a record matching the cacheKey option, the cached data is compared against the current timestamps on both the config file and the source files. If the file system indicates that the cached data may be out of date, the wrapper will ignore the cached data and then wait for webpack to complete a fresh build.

If the watch option is set to true, as soon as the cached data is served, the watcher is started in the background.

Whenever a compiler successfully builds, the cache is immediately updated with the output from the build process.

If you want to read cache files from another process, you should probably define the cacheKey or hash options to ensure that the cache entries are easily accessible.

Builds

Builds are functions which mutate a config file to reflect varying environments.

Builds should be specified in your config file under a builds object which contains functions. The functions should return a config object which can be read by webpack's compiler.

// In your config file

var builds = require('webpack-wrapper/lib/builds');

module.exports = {
  // ...
  builds: {
    dev: function(config, opts) {
      config.devtool = 'eval';

      config.loaders.push({
        // ...
      });

      return config;
    },
    prod: function(config, opts) {
      config.devtool = 'source-map';
      
      return config
    }
  }
};

To apply any builds, simply pass in the build option to the wrapper

var webpack = require('webpack-wrapper');

webpack({
  // ...
  build: 'dev'
}, function(err, stats) {
  // ...
});

The wrapper comes with some typical builds that you can apply to handle common situations.

// In your config file

var builds = require('webpack-wrapper/lib/builds');

module.exports = {
  // ...
  builds: {
    dev: function(config, opts) {
      // Apply the wrapper's dev build
      config = builds.dev(config, opts);

      // Apply the wrapper's hmr build
      config = builds.hmr(config, opts);

      return config;
    }
  }
};

improve

require('webpack-wrapper/lib/builds').improve;

Adds new webpack.optimize.OccurrenceOrderPlugin()

Adds new webpack.NoErrorsPlugin()

dev

require('webpack-wrapper/lib/builds').dev;

Applies the improve build

Sets devtool to eval-source-maps

Sets output.pathinfo to true

Adds

new webpack.DefinePlugin({
  'process.env': {
    NODE_ENV: JSON.stringify('development')
  }
})

hmr

require('webpack-wrapper/lib/builds').hmr;

Applies the improve build

Adds webpack-wrapper/lib/hmr/client?... and webpack/hot/only-dev-server to the config's entries. These enable the client-side to talk to the HMR endpoint.

Adds new webpack.HotModuleReplacementPlugin()

Sets output.publicPath to the value of the staticUrl option

Sets recordsPath to path.join(opts.outputPath, 'webpack.records-' + opts.hash + '.json');

prod

require('webpack-wrapper/lib/builds').prod;

Applies the improve build

Sets devtool to source-map

Adds new webpack.optimize.DedupePlugin()

Adds new webpack.optimize.UglifyJsPlugin()

Adds

new webpack.DefinePlugin({
  'process.env': {
    NODE_ENV: JSON.stringify('production')
  }
})

HMR

The wrapper includes hooks to add HMR functionality to both your front-end and back-end.

// To use it with express

var http = require('http');
var express = require('express');
var webpack = require('webpack-wrapper');

var app = express();
var server = http.Server(app);

webpack.hmr.addTo(server);

server.listen(8000);

The addTo method adds a socket.io handler to the endpoint defined by the hmrPath option, which defaults to /__webpack_hmr__. You can provide a second argument to addTo to change the path, but you'll need to provide that same value as the hmrPath option whenever you call the wrapper.

And ensure that you inform the wrapper to apply the hmr build with respect to your server setup

var webpack = require('webpack-wrapper');

webpack({
  // ...
  outputPath: '/path/to/dir',
  staticUrl: '/static',
  hmr: true,
  hmrRoot: 'http://127.0.0.1:8000',
}, function(err, stats) {
  // ...
});

Colophon

Large portions of this codebase are heavily indebted to webpack-dev-middleware and webpack-dev-server.

This project stands on the shoulders of giants - specifically, Tobias Koppers and the webpack ecosystem's vast number of contributors.