Repository files navigation

HTML Webpack Plugin

Plugin that simplifies creation of HTML files to serve your bundles

  npm i --save-dev html-webpack-plugin

  yarn add --dev html-webpack-plugin

  npm i --save-dev html-webpack-plugin@4

  yarn add --dev html-webpack-plugin@4

This is awebpack plugin that simplifies creation of HTML files to serve yourwebpack bundles. This is especially useful forwebpack bundles that include a hash in the filename which changes every compilation. You can either let the plugin generate an HTML file for you, supplyyour own template usinglodash templates or use your own loader.

Thanks for supporting the ongoing improvements to the html-webpack-plugin!

Thehtml-webpack-plugin works without configuration.
It's a great addition to the⚙️ webpack-config-plugins.

Thehtml-webpack-plugin provideshooks to extend it to your needs. There are already some really powerful plugins which can be integrated with zero configuration

• webpack-subresource-integrity for enhanced asset security
• appcache-webpack-plugin for iOS and Android offline usage
• favicons-webpack-plugin which generates favicons and icons for iOS, Android and desktop browsers
• html-webpack-harddisk-plugin can be used to always write to disk the html file, useful when webpack-dev-server / HMR are being used
• html-webpack-inline-svg-plugin to inline SVGs in the resulting HTML file.
• html-webpack-exclude-assets-plugin for excluding assets using regular expressions
• html-webpack-include-assets-plugin for including lists of js or css file paths (such as those copied by the copy-webpack-plugin).
• html-webpack-injector to inject chunks inhead orbody (different locations ) of same html document.
• resource-hints-webpack-plugin to add resource hints for faster initial page loads using<link rel='preload'> and<link rel='prefetch'>
• link-media-html-webpack-plugin allows for injected stylesheet<link /> tags to have their media attribute set automatically; useful for providing specific desktop/mobile/print etc. stylesheets that the browser will conditionally download
• html-webpack-inline-style-plugin for inlining styles to HTML elements usingjuice. Useful for email generation automatisation.
• html-webpack-exclude-empty-assets-plugin removes empty assets from being added to the html. This fixes some problems with extract-text-plugin with webpack 4.
• webpack-concat-plugin for concat and uglify files that needn't to be webpack bundles(for legacy files) and inject to html-webpack-plugin.
• html-webpack-link-type-plugin adds a configurable mimetype to resources injected as links (such as adding type="text/css" to external stylesheets) for compatibility with "strict mode".
• csp-html-webpack-plugin to addContent Security Policy meta tags to the HTML output
• strict-csp-html-webpack-plugin to add astrict Content-Security-Policy (CSP) as ameta tag to the HTML output. A strict CSP is specifically efficient against XSS attacks.
• webpack-nomodule-plugin allows you to add anomodule attribute to specific injected scripts, which prevents the scripts from being loaded by newer browsers. Good for limiting loads of polyfills.
• html-webpack-skip-assets-plugin Skip adding certain output files to the html file. Built as a drop-in replacement forhtml-webpack-exclude-assets-plugin and works with newerhtml-webpack-plugin versions
• html-webpack-inject-preload allows to add preload links <link rel='preload'> anywhere you want.
• inject-body-webpack-plugin is a simple method of injecting a custom HTML string into the body.
• html-webpack-plugin-django a Webpack plugin to inject Django static tags.
• html-webpack-inject-attributes-plugin add extra attributes to inject assetTags.
• js-entry-webpack-plugin creates webpack bundles into your js entry

The plugin will generate an HTML5 file for you that includes all yourwebpackbundles in the head usingscript tags. Just add the plugin to yourwebpackconfig as follows:

webpack.config.js

constHtmlWebpackPlugin=require("html-webpack-plugin");module.exports={entry:"index.js",output:{path:__dirname+"/dist",filename:"index_bundle.js",},plugins:[newHtmlWebpackPlugin()],};

This will generate a filedist/index.html containing the following

<!doctype html><html><head><metacharset="utf-8"/><title>Webpack App</title><scriptdefersrc="index_bundle.js"></script></head><body></body></html>

If you have multiplewebpack entry points, they will all be included withscript tags in the generated HTML.

If you have any CSS assets in webpack's output (for example, CSS extracted with themini-css-extract-plugin)then these will be included with<link> tags in the HTML head.

If you have plugins that make use of it,html-webpack-plugin should be ordered first before any of the integrated Plugins.

You can pass a hash of configuration options tohtml-webpack-plugin.Allowed values are as follows:

Here's an example webpack config illustrating how to use these options

webpack.config.js

{entry:'index.js',output:{path:__dirname+'/dist',filename:'index_bundle.js'},plugins:[newHtmlWebpackPlugin({title:'My App',filename:'assets/admin.html'})]}

To generate more than one HTML file, declare the plugin more thanonce in your plugins array

webpack.config.js

{entry:'index.js',output:{path:__dirname+'/dist',filename:'index_bundle.js'},plugins:[newHtmlWebpackPlugin(),// Generates default index.htmlnewHtmlWebpackPlugin({// Also generate a test.htmlfilename:'test.html',template:'src/assets/test.html'})]}

If the default generated HTML doesn't meet your needs you can supplyyour own template. The easiest way is to use thetemplate option and pass a custom HTML file.The html-webpack-plugin will automatically inject all necessary CSS, JS, manifestand favicon files into the markup.

Details of other template loaders aredocumented here.

plugins:[newHtmlWebpackPlugin({title:"Custom template",// Load a custom template (lodash by default)template:"index.html",}),];

index.html

<!doctype html><html><head><metacharset="utf-8"/><title><%= htmlWebpackPlugin.options.title %></title></head><body></body></html>

If you already have a template loader, you can use it to parse the template.Please note that this will also happen if you specify the html-loader and use.html file as template.

webpack.config.js

module:{loaders:[{test:/\.hbs$/,loader:"handlebars-loader"}]},plugins:[newHtmlWebpackPlugin({title:'Custom template using Handlebars',template:'index.hbs'})]

You can use thelodash syntax out of the box. If theinject feature doesn't fit your needs and you want full control over the asset placement use thedefault template of thehtml-webpack-template project as a starting point for writing your own.

The following variables are available in the template by default (you can extend them using thetemplateParameters option):

• htmlWebpackPlugin: data specific to this plugin

  • htmlWebpackPlugin.options: the options hash that was passed tothe plugin. In addition to the options actually used by this plugin,you can use this hash to pass arbitrary data through to your template.

  • htmlWebpackPlugin.tags: the preparedheadTags andbodyTags Array to render the<base>,<meta>,<script> and<link> tags.Can be used directly in templates and literals. For example:

    <html><head><%= htmlWebpackPlugin.tags.headTags %></head><body><%= htmlWebpackPlugin.tags.bodyTags %></body></html>

  • htmlWebpackPlugin.files: direct access to the files used during the compilation.

    publicPath:string;js:string[];css:string[];manifest?:string;favicon?:string;

• webpackConfig: the webpack configuration that was used for this compilation. Thiscan be used, for example, to get thepublicPath (webpackConfig.output.publicPath).

• compilation: the webpackcompilation object.This can be used, for example, to get the contents of processed assets and inline themdirectly in the page, throughcompilation.assets[...].source()(seethe inline template example).

The template can also be directly inlined directly into the options object.
⚠️templateContent does not allow to use webpack loaders for your template and will not watch for template file changes

webpack.config.js

newHtmlWebpackPlugin({templateContent:`    <html>      <body>        <h1>Hello World</h1>      </body>    </html>  `,});

ThetemplateContent can also access alltemplateParameters values.
⚠️templateContent does not allow to use webpack loaders for your template and will not watch for template file changes

webpack.config.js

newHtmlWebpackPlugin({inject:false,templateContent:({ htmlWebpackPlugin})=>`    <html>      <head>${htmlWebpackPlugin.tags.headTags}      </head>      <body>        <h1>Hello World</h1>${htmlWebpackPlugin.tags.bodyTags}      </body>    </html>  `,});

To include only certain chunks you can limit the chunks being used

webpack.config.js

plugins:[newHtmlWebpackPlugin({chunks:["app"],}),];

It is also possible to exclude certain chunks by setting theexcludeChunks option

webpack.config.js

plugins:[newHtmlWebpackPlugin({excludeChunks:["dev-helper"],}),];

If theminify option is set totrue (the default when webpack'smode is'production'),the generated HTML will be minified usinghtml-minifier-terserand the following options:

{collapseWhitespace:true,keepClosingSlash:true,removeComments:true,removeRedundantAttributes:true,removeScriptTypeAttributes:true,removeStyleLinkTypeAttributes:true,useShortDoctype:true}

To use customhtml-minifier optionspass an object tominify instead. This object will not be merged with the defaults above.

To disable minification during production mode set theminify option tofalse.

If themeta option is set the html-webpack-plugin will inject meta tags.
For the default template the html-webpack-plugin will already provide a default for theviewport meta tag.

Please take a look at this well maintained list of almost allpossible meta tags.

Most meta tags are configured by setting aname and acontent attribute.
To add those use a key/value pair:

webpack.config.js

plugins:[newHtmlWebpackPlugin({meta:{viewport:"width=device-width, initial-scale=1, shrink-to-fit=no",// Will generate: <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">"theme-color":"#4285f4",// Will generate: <meta name="theme-color" content="#4285f4">},}),];

Thehttp-equiv attribute is essentially used to simulate a HTTP response header.
This format is supported using an object notation which allows you to add any attribute:

webpack.config.js

plugins:[newHtmlWebpackPlugin({meta:{"Content-Security-Policy":{"http-equiv":"Content-Security-Policy",content:"default-src https:",},// Will generate: <meta http-equiv="Content-Security-Policy" content="default-src https:">// Which equals to the following http header: `Content-Security-Policy: default-src https:`"set-cookie":{"http-equiv":"set-cookie",content:"name=value; expires=date; path=url",},// Will generate: <meta http-equiv="set-cookie" content="value; expires=date; path=url">// Which equals to the following http header: `set-cookie: value; expires=date; path=url`},}),];

When thebase option is used,html-webpack-plugin will inject abase tag.By default, a base tag will not be injected.

The following two are identical and will both insert<base href="http://example.com/some/page.html">:

newHtmlWebpackPlugin({base:"http://example.com/some/page.html",});

newHtmlWebpackPlugin({base:{href:"http://example.com/some/page.html"},});

Thetarget can be specified with the corresponding key:

newHtmlWebpackPlugin({base:{href:"http://example.com/some/page.html",target:"_blank",},});

which will inject the element<base href="http://example.com/some/page.html">.

For long term caching addcontenthash to the filename.

Example:

plugins:[newHtmlWebpackPlugin({filename:"index.[contenthash].html",}),];

contenthash is the hash of the content of the output file.

Refer webpack'sTemplate Strings for more details

To allow otherplugins to alter the HTML this plugin executestapable hooks.

Thelib/hooks.js contains all informationabout which values are passed.

    AsyncSeriesWaterfallHook<{      assets: {        publicPath: string,        js: Array<{string}>,        css: Array<{string}>,        favicon?: string | undefined,        manifest?: string | undefined      },      outputName: string,      plugin: HtmlWebpackPlugin    }>

    AsyncSeriesWaterfallHook<{      assetTags: {        scripts: Array<HtmlTagObject>,        styles: Array<HtmlTagObject>,        meta: Array<HtmlTagObject>,      },      publicPath: string,      outputName: string,      plugin: HtmlWebpackPlugin    }>

    AsyncSeriesWaterfallHook<{      headTags: Array<HtmlTagObject | HtmlTagObject>,      bodyTags: Array<HtmlTagObject | HtmlTagObject>,      publicPath: string,      outputName: string,      plugin: HtmlWebpackPlugin    }>

    AsyncSeriesWaterfallHook<{      html: string,      headTags: Array<HtmlTagObject | HtmlTagObject>,      bodyTags: Array<HtmlTagObject | HtmlTagObject>,      outputName: string,      plugin: HtmlWebpackPlugin,    }>

    AsyncSeriesWaterfallHook<{      html: string,      outputName: string,      plugin: HtmlWebpackPlugin,    }>

    AsyncSeriesWaterfallHook<{      outputName: string,      plugin: HtmlWebpackPlugin    }>

Example implementation:webpack-subresource-integrity

plugin.js

// If your plugin is direct dependent to the html webpack plugin:constHtmlWebpackPlugin=require("html-webpack-plugin");// If your plugin is using html-webpack-plugin as an optional dependency// you can use https://github.com/tallesl/node-safe-require instead:constHtmlWebpackPlugin=require("safe-require")("html-webpack-plugin");classMyPlugin{apply(compiler){compiler.hooks.compilation.tap("MyPlugin",(compilation)=>{console.log("The compiler is starting a new compilation...");// Static Plugin interface |compilation |HOOK NAME | register listenerHtmlWebpackPlugin.getCompilationHooks(compilation).beforeEmit.tapAsync("MyPlugin",// <-- Set a meaningful name here for stacktraces(data,cb)=>{// Manipulate the contentdata.html+="The Magic Footer";// Tell webpack to move oncb(null,data);},);});}}module.exports=MyPlugin;

webpack.config.js

plugins:[newMyPlugin({options:""})];

Note that the callback must be passed the HtmlWebpackPluginData in order to pass this onto any other plugins listening on the samebeforeEmit event

Jan Nicklas

Thomas Sileghem

Thank you to all our backers!
If you want to support the project as wellbecome a sponsor or aa backer.

This project exists thanks to all the people who contribute.

You're free to contribute to this project by submittingissues and/orpull requests. This project is test-driven, so keep in mind that every change and new feature should be covered by tests.