webpack-wrapper
v0.6.2
Published
A wrapper library around webpack which provides a variety of optimisations and utilities
Downloads
7
Readme
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
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.