- Notifications
You must be signed in to change notification settings - Fork3
jharris4/html-webpack-deploy-plugin
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Enhanceshtml-webpack-plugin allowing you tocopyassets ornode_modules package assets into your webpack build andinject them as tags into yourhtml.
Built on top of thehtml-webpack-tags andcopy-webpack plugins.
$ npm install --save-dev html-webpack-deploy-plugin
You must be runningNode 10.0 along withWebpack 5.0 or higher for version
3.xof this plugin.You must be runningNode 8.6 or higher for version
2.xof this plugin.This plugin wasrenamed from
html-webpack-deploy-assets-plugintohtml-webpack-deploy-pluginin version2.x.For use with the
Node < 8.6please use version1.x(old READMEhere)
ThechunksSortMode option ofhtml-webpack-plugin3.x has adefault value ofauto.
This option is known to cause issues withcode splitting orlazy loaded bundles (#981).
When using this plugin with version3.x you should set thischunksSortMode to'none', like this:
newHtmlWebpackPlugin({chunksSortMode:'none'})
The plugin configuration is specified by an optionsobject passed to its constructor.
This object has anassets option for copying & injecting local files, and apackages option for copying & injecting packages from your localnode_modules directory.
newHtmlWebpackDeployPlugin({assets:{copy:[{from:'a',to:'b'}],links:['b/my.css',{hash:false,publicPath:false,path:'b/my.png',attributes:{rel:'icon'}}],scripts:'b/my.js'},packages:{'bootstrap':{copy:[{from:'dist/bootstrap.min.css',to:'bootstrap.min.css'}],links:{useCdn:true,path:'bootstrap.min.css',cdnPath:'dist/bootstrap.min.css'},},'react':{copy:[{from:'umd',to:''}],scripts:{variableName:'React',path:'react.production.min.js',cdnPath:'umd/react.production.min.js',}},'react-dom':{copy:[{from:'umd',to:''}],scripts:{variableName:'ReactDOM',path:'react-dom.production.min.js',cdnPath:'umd/react-dom.production.min.js',},useCdn:false}},useCdn:true,getCdnPath:(packageName,packageVersion,packagePath)=>`https://unpkg.com/${packageName}@${packageVersion}/${packagePath}`});
All options for this plugin arevalidated as soon as the plugin is instantiated.
Options areinherited by inner levels of the config and will be overridden if specified in a level.
The available options are described below, grouped by at whatlevel in the plugin config they may be used.
These options are only available at the root level of the plugin config.
| Name | Type | Default | Description |
|---|---|---|---|
assets | {Object} | undefined | The local assets to copy into the webpack output directory and inject into the template html file |
packages | {Object} | undefined | Thenode_modules packages to copy into the webpack output directory and inject into the template html file |
useAssetsPath | {Boolean} | true | Whether or not to prefix all assets with theassetsPath |
addAssetsPath | {Function} | see below | The function to call to get the output path for assets when copying and injecting them |
assetsPath | {Boolean|String|Function} | undefined | Shortcut for specifying bothuseAssetsPath andaddAssetsPath at the same time |
usePackagesPath | {Boolean} | true | Whether or not to prefix all packages with thepackagesPath |
addPackagesPath | {Function} | see below | The function to call to get the output path forpackages when copying and injecting them |
packagesPath | {Boolean|String|Function} | undefined | Shortcut for specifying bothusePackagesPath andaddPackagesPath at the same time |
getPackagePath | {Function} | see below | The function to call to get the output path for apackage &version when copying and injecting it |
findNodeModulesPath | {Function} | see below | The function to call to find thenode_modules directory where packages to be deployed are installed so theirversion can be read from theirpackage.json file. The default is to search upwards in the current working directory |
files | {Array<String>} | [] | If specified this plugin will only inject tags into the html-webpack-plugin instances that are injecting into these files (usesminimatch) |
prependExternals | {Boolean} | true | Whether to defaultappend tofalse for any<script>tag that has anexternal orvariableName option specified |
Several options from thehtml-webpack-tags-plugin are available at all levels.
Options are passed down the levels, and overriden if specified at a lower level.
| Name | Type | Default | Description |
|---|---|---|---|
append | {Boolean} | true | Whether to prepend or append the injected tags relative to any existing or webpack bundle tags (should be set tofalse when using anyscript tagexternal) |
useHash | {Boolean} | false | Whether to inject the webpackcompilation.hash into the tag paths |
addHash | {Function(assetPath:String, hash:String):String} | see below | The function to call when injecting thehash into the tag paths |
hash | {Boolean|Function} | undefined | Shortcut to specifyinguseHash andaddHash |
usePublicPath | {Boolean} | true | Whether to inject the (webpack)publicPath into the tag paths |
addPublicPath | {Function(assetPath:String, publicPath:String):String} | see below | Whether to inject thepublicPath into the tag paths |
publicPath | {Boolean|String|Function} | undefined | Shortcut to specifyingusePublicPath andaddPublicPath |
| Name | Type | Default | Description |
|---|---|---|---|
links | {String|Object|Array<String|Object>} | [] | The tags to inject as<link> html tags |
scripts | {String|Object|Array<String|Object>} | [] | The tags to inject as<script> html tags |
copy | `{Array | Object}` | [] |
| Name | Type | Default | Description |
|---|---|---|---|
copy.fromAbsolute | {Boolean} | false | When set to true, thecopy.from willnot be prefixed with the package'snode_modules relative path |
| Name | Type | Default | Description |
|---|---|---|---|
useCdn | {Boolean} | false | Whether or not to use thegetCdnPath to replace the tag paths with theircdn urls |
getCdnPath | {Function} | see below | The function to use when replacing tag paths withcdn urls |
The availabletag options forlinks orscripts are defined by thehtml-webpack-tags-plugin.
Additionaltag options are defined by this plugin:
| Name | Type | Default | Description |
|---|---|---|---|
devPath | {String} | optional | Alternative path to use for the tag whenwebpack.mode === "development". Only used when theuseCdn option inherited by the tag is false |
cdnPath | {String} | optional | Alternative path to use for the tag when theuseCdn option inherited by the tag is true |
This plugin will run and do nothing if no options ({}) are provided.
The default options for this plugin are shown below:
constpath=require('path');constfindUp=require('find-up');constslash=require('slash');// fixes slashes in file paths for windowsconstDEFAULT_OPTIONS={assets:{},packages:{},useAssetsPath:true,addAssetsPath:assetPath=>path.join('assets',assetPath),usePackagesPath:true,addPackagesPath:packagePath=>path.join('packages',packagePath),getPackagePath:(packageName,packageVersion,packagePath)=>path.join(packageName+'-'+packageVersion,packagePath),findNodeModulesPath:(cwd,packageName)=>findUp.sync(slash(path.join('node_modules',packageName)),{ cwd}),useCdn:false,getCdnPath:(packageName,packageVersion,packagePath)=>`https://unpkg.com/${packageName}@${packageVersion}/${packagePath}`};
Theassets option can be used to specify local assets that should be copied to the webpack output directory and injected into theindex.html as tags.
This option requires an object with any of thecopy,links, orscripts properties.
The settings for these are based on thecopy-webpack-plugin and thehtml-webpack-tags-plugin
For example, to copy some assets to webpack, and insert a<link> and<script> tag:
constpluginOptions={assets:{copy:[{from:'src-path/assets',to:'dst-path/assets'},{from:'src-path/js',to:'dst-path/js'},{from:'src-path/css/src-file.png',to:'dst-path/dst-file.png'}],links:[{path:'dst-path/dst-file.png',attributes:{rel:'icon'}],scripts:[{path:'dst-path/js/script.js',}]}};
The above example will generate something like the following html:
<head><linkhref="${webpack.publicPath}dst-path/dst-file.png"rel="icon"></head><body><scriptsrc="${webpack.publicPath}dst-path/js/script.js"></script></body>
Thepackages option can be used to specify package assets that should be copied to the webpack output directory and injected into theindex.html as tags.
This option requires an object with any of thecopy,links, orscripts properties.
The settings for these are based on thecopy-webpack-plugin and thehtml-webpack-tags-plugin
For example, to copy some assets frombootstrap to webpack, and insert a<link> and<script> tag for bootstrap:
constpluginOptions={packages:{'bootstrap':{copy:[{from:'dist/css',to:'css/'},{from:'dist/js',to:'js/'}],links:['css/bootstrap.min.css'],scripts:{variableName:'Bootstrap',path:'js/bootstrap.bundle.min.js'}}}};
ThevariableName can be used to tellwebpack to stop bundling a package, and instead load it from the injected<script>.
The above example will generate something like the following html:
<head><linkhref="${webpack.publicPath}css/bootstrap.min.css"></head><body><scriptsrc="${webpack.publicPath}js/bootstrap.bundle.min.js"></script></body>
DeployingBootstrap css and fonts and an assets directory from local files:
plugins:[newHtmlWebpackPlugin(),newHtmlWebpackDeployAssetsPlugin({packages:{'bootstrap':{copy:[{from:'dist/css',to:'css/'},{from:'dist/fonts',to:'fonts/'}],links:['css/bootstrap.min.css','css/bootstrap-theme.min.css']}},assets:{copy:[{from:'src/assets',to:'assets/'}],links:{path:'/assets/icon.png',attributes:{rel:'icon'}}}})]
This will generate aindex.html something like:
<!DOCTYPE html><html><head><metacharset="UTF-8"><title>Webpack App</title><linkhref="any-webpack-generated-styles.css"rel="stylesheet"><linkhref="bootstrap-3.3.7/css/bootstrap.min.css"rel="stylesheet"><linkhref="bootstrap-3.3.7/css/bootstrap-theme.min.css"rel="stylesheet"><linkhref="/assets/icon.png"rel="icon"></head><body><scriptsrc="any-webpack-generated-bundles.js"></script></body></html>
Note that additionally, the contents of the following directories will be copied:
node_modules/bootstrap/dist/css ->dist/bootstrap-3.3.7/cssnode_modules/bootstrap/dist/fonts ->dist/bootstrap-3.3.7/fontssrc/assets ->dist/assets
DeployingReact from aCDN:
plugins:[newHtmlWebpackPlugin(),newHtmlWebpackDeployAssetsPlugin({packages:{'react':{copy:[{from:'umd',to:''}],scripts:{variableName:'React',path:'react.production.min.js',cdnPath:'umd/react.production.min.js',}},'react-dom':{copy:[{from:'umd',to:''}],scripts:{variableName:'ReactDOM',path:'react-dom.production.min.js',cdnPath:'umd/react-dom.production.min.js',}}}useCdn:true,getCdnPath:(packageName,packageVersion,packagePath)=>`https://unpkg.com/${packageName}@${packageVersion}/${packagePath}`})]
This will generate aindex.html with your webpack bundled outputand the following:
<!DOCTYPE html><html><head><metacharset="UTF-8"><title>Webpack App</title><linkhref="any-webpack-generated-styles.css"rel="stylesheet"></head><body><scriptsrc="https://unpkg.com/react@16.8.6/umd/react.production.js"></script><scriptsrc="https://unpkg.com/react-dom@16.8.6/umd/react-dom.production.js"></script><scriptsrc="any-webpack-generated-bundles.js"></script><!-- react & react-dom were removed from webpack bundles automatically --></body></html>
DeployingReact fromLocal UMD Bundles:
plugins:[newHtmlWebpackPlugin(),newHtmlWebpackDeployAssetsPlugin({packages:{'react':{copy:[{from:'umd',to:''}],scripts:{variableName:'React',path:'react.production.min.js',devPath:'react.development.js'}},'react-dom':{copy:[{from:'umd',to:''}],scripts:{variableName:'ReactDOM',path:'react-dom.production.min.js',devPath:'react-dom.development.js'}}}})]
This copiesreact andreact-dom into webpack's output directory, versioning the directory automatically based on their installed version. They can now be referenced from the tag paths in the html.
Webpack is instructed thatreact andreact-dom areexternal so they areno longer bundled by webpack.
The generatedindex.html looks like:
<!DOCTYPE html><html><head><metacharset="UTF-8"><title>Webpack App</title><linkhref="any-webpack-generated-styles.css"rel="stylesheet"></head><body><scriptsrc="my-public-path/packages/react-16.8.6/react.production.min.js"></script><scriptsrc="my-public-path/packages/react-dom-16.8.6/react-dom.production.min.js"></script><scriptsrc="any-webpack-generated-bundles.js"></script><!-- react & react-dom were removed from webpack bundles automatically --></body></html>
Or indevelopment mode because thedevPath option was specified, the generatedindex.html looks like:
<!DOCTYPE html><html><head><metacharset="UTF-8"><title>Webpack App</title><linkhref="any-webpack-generated-styles.css"rel="stylesheet"></head><body><scriptsrc="my-public-path/packages/react-16.8.6/react.development.js"></script><scriptsrc="my-public-path/packages/react-dom-16.8.6/react-dom.development.js"></script><scriptsrc="any-webpack-generated-bundles.js"></script><!-- react & react-dom were removed from webpack bundles automatically --></body></html>
When doing custom deployment without a CDN it can be useful to configure the directories that all assets and packages are copied to and served from.
The following examples show some useful settings for such situations.
Disabling the grouping of assets into theassets directory:
newHtmlWebpackDeployAssetsPlugin({useAssetsPath:false});
<linkhref="my-public-path/assets/file.css"><scriptsrc="my-public-path/assets/file.js"></script>
becomes:
<linkhref="my-public-path/file.css"><scriptsrc="my-public-path/file.js"></script>
Custom grouping of assets into aconfigurable directory:
newHtmlWebpackDeployAssetsPlugin({assetsPath:'my-assets-path'});
<linkhref="my-public-path/assets/file.css"><scriptsrc="my-public-path/assets/file.js"></script>
becomes:
<linkhref="my-public-path/my-assets-path/file.css"><scriptsrc="my-public-path/my-assets-path/file.js"></script>
Disabling the grouping of packages into thepackages directory:
newHtmlWebpackDeployAssetsPlugin({usePackagesPath:false});
<linkhref="my-public-path/packages/bootstrap-4.3.1/bootstrap.min.css"><scriptsrc="my-public-path/packages/react-16.8.6/react.production.min.js"></script>
becomes:
<linkhref="my-public-path/bootstrap-4.3.1/bootstrap.min.css"><scriptsrc="my-public-path/react-16.8.6/react.production.min.js"></script>
Custom grouping of packages into aconfigurable directory:
newHtmlWebpackDeployAssetsPlugin({packagesPath:'my-packages-path'});
<linkhref="my-public-path/packages/bootstrap-4.3.1/bootstrap.min.css"><scriptsrc="my-public-path/packages/react-16.8.6/react.production.min.js"></script>
becomes:
<linkhref="my-public-path/my-packages-path/bootstrap-4.3.1/bootstrap.min.css"><scriptsrc="my-public-path/my-packages-path/react-16.8.6/react.production.min.js"></script>
About
Deploy assets or node_modules package assets with html webpack plugin
Resources
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors2
Uh oh!
There was an error while loading.Please reload this page.