Gulp Inject Webpack Plugin
A Webpack plugin that wraps gulp-inject for use with the Webpack CLI
Gulp has an excellect HTML composer called Gulp Inject. It has a lot of powerful features.
If you have existing projects that you are migrating to Webpack it is desirable for these features to work immediately, with the Webpack CLI.
This plugin wraps Gulp Inject so that you can use it without running Gulp. It has a dependency on the Vinyl File System used in Gulp but not on Gulp itself.
This makes the plugin somewhat of a frankenstein, however the excellent implementation of Gulp Inject makes it compelling nonetheless. Over time I am sure we can find a more elegant solution for html injection in Webpack.
To that end, please also consider html-webpack-plugin if you do not need the feature-set of this plugin.
webpack.config.js file the plugin should be instantiated as follows:
target assetsOrChunks options
stringname of a chunk containing a html asset or a html asset relative to
output.path. It will be edited in place.
assetsOrChunksis a single
Array.<string|RegExp>list of chunk names and/or asset names relative to
optionsis an optional hash
objectof options per the Gulp Inject API.
In full this would look like the following:
var IndexHTMLPlugin =ChunkManifestPlugin =GulpInjectPlugin = ;moduleexports =context : __dirnameentry :html : './src/index.html'vendor: './src/vendor.js'index : './src/index.js'output :path : './build'filename : 'assets/[name].[chunkhash].js'chunkFilename : 'assets/[name].[chunkhash].js'devtoolModuleFilenameTemplate : '[absolute-resource-path]'devtoolFallbackModuleFilenameTemplate: '[absolute-resource-path]?[hash]'module :loaders:test : /\.html?$/iloader: 'html?removeComments=false&attrs=img:src link:href'plugins :'html' 'index.html''html' 'manifest.json' 'vendor' /^vendor\./ 'index'
output options should be configured to your own taste, but it is a good idea to use a
chunkhash for long term caching.
Note the usage of
IndexHTMLPlugin. This allows you to add assets such as
favicon.ico to your HTML such that they are processed by Webpack.
Note the usage of
ChunkManifestPlugin. This is important for long term caching and will produce a
manifest.json that should be injected as the first item.
Note the usage of a Regular Expression for the
vendor chunk. This will allow you to do bundle splitting as discussed below.
./src/index.html of the Webpack configuration is the source file for your project html file.
This source file should include the necessary injection placeholder comments used by Gulp Inject. For example:
<!DOCTYPE html><html><head><!-- inject:css --><!-- endinject --></head><body><!-- inject:json --><!-- endinject --><!-- inject:js --><!-- endinject --></body></html>
Note that the additional
<!-- inject:json --> placeholder is necessary where you wish to inject the cache manifest
Where the optional
options hash is specified it is passed to Gulp Inject.
options.quiet is asserted by default. This prevents Gulp Inject from creating log output in the Gulp Utils format. However you may find this option useful for debugging problems.
Regular Expressions (Bundle Splitting)
Sure we could automatically detect the files omitted in your compile and pass them to Gulp Inject. However we would not be able to determine the correct order.
Chunk order is important, and it may even be that certain chunks should only be included in certain
html files. For this reason we do not automatically detect and the
assetsOrChunks list is explicit.
But your code may define arbitrary split points and you wont't want this to be coupled with the
assetsOrChunks list in your configuration. We can remedy this by using one or more
Regular Expression elements in the
assetsOrChunks list. The limitation being you must name chunks in order to write a meaningful expression.
Here is an example for a simple
vendor.js, split using common-js syntax to split chunk
vendor into chunks
The otherwise empty
vendor chunk will be the entry chunk and will contain the Webpack prelude. Therefore it needs to come first. The order in which the remaining
vendor.* chunks are injected does not matter because
require.ensure() determines the execution order. Therefore we can group them all together with the single expression
/^vendor\./. All of this is shown in the example configuration above.
In addition to the default transforms the plugin adds a transform for
.json files which will embed the Cache Manifest JSON data in the page.
Similar to Gulp Inject, all transforms are exported under the hash
GulpInjectPlugin.transform.html.json expects the default manifest variable name of
webpackManifest. However you may change it by using a more explicit plugin configuration.
moduleexports =...plugins:'html' 'index.html'filename : 'foo.json'manifestVariable: 'bar''index''foo.json'transform: GulpInjectPlugintransformhtmljson
Don't forget to include a JSON injection placeholder, such as
<!-- inject:json -->, in your HTML source file.