html-webpack-tags-plugin

3.0.2 verified Sat Apr 25 auth: no javascript

A webpack plugin that extends html-webpack-plugin to inject custom JS, CSS, or arbitrary tags (scripts, links, meta, etc.) into the generated HTML. Version 3.0.2 is the latest stable release, released on an irregular cadence. The plugin supports both appending and prepending assets, glob patterns for dynamic asset inclusion, and custom attributes on injected tags. It ships TypeScript types and requires webpack 5 and html-webpack-plugin 5 as peer dependencies. Key differentiator: unlike html-webpack-plugin's built-in asset injection, this plugin allows injecting files not tracked by webpack's compilation (e.g., copied via copy-webpack-plugin) and non-standard tags.

Common errors

error TypeError: HtmlWebpackTagsPlugin is not a constructor ↓

cause CommonJS require returns an object with 'default' property; using it directly as a constructor fails.

fix

Use const HtmlWebpackTagsPlugin = require('html-webpack-tags-plugin').default;

error Error: options.tags must be an array of objects with tagName property ↓

cause The 'tags' option was passed a string or invalid object (e.g., missing 'tagName').

fix

Ensure each tag is an object with at least 'tagName' and optionally 'path' and 'attributes'. Example: { tagName: 'script', path: 'app.js' }

error Module not found: Error: Can't resolve 'html-webpack-tags-plugin' ↓

cause The package is not installed or is in devDependencies but not installed when running webpack outside dev mode.

fix

Run 'npm install --save-dev html-webpack-tags-plugin' and ensure it is in the devDependencies.

error Critical dependency: require function is used in a way in which dependencies cannot be statically extracted ↓

cause Using a dynamic path in the 'path' property of a tag without wrapping it in a string literal.

fix

Use a static string or a variable that resolves to a known path. Avoid using expressions like path: require('path').join(__dirname, 'file.js') directly in the options object.

Warnings

breaking In v3, the options format changed significantly. The 'assets' array of version 2 is replaced by 'tags' objects with explicit 'tagName', 'path', and 'attributes'. Old 'assets' and 'append' options on the tags are no longer supported. ↓

fix Use the new 'tags' array with objects containing 'tagName', 'path', 'attributes', etc. See migration guide.

breaking In v3, the default export changed. In CommonJS, you must use require('html-webpack-tags-plugin').default instead of require('html-webpack-tags-plugin'). ↓

fix Use const HtmlWebpackTagsPlugin = require('html-webpack-tags-plugin').default;

deprecated The 'publicPath' option in tags is deprecated in v3. Instead, use 'publicPath' globally in the plugin options or set it per tag using 'attributes'. ↓

fix Set 'publicPath: true/false' in the plugin options object, or omit it per tag.

gotcha If you use 'append: false' globally, tags are prepended before html-webpack-plugin's auto-generated assets. This may cause ordering issues if you rely on a specific sequence. ↓

fix Use 'append: true' to append after auto assets, or control order via multiple plugin instances.

gotcha The plugin does not handle webpack's publicPath automatically in all cases. If 'publicPath' option is not set, absolute paths may be missing the public path prefix. ↓

fix Set 'publicPath: true' in the plugin options to prepend the webpack publicPath to relative tag paths.

Install

npm install html-webpack-tags-plugin

yarn add html-webpack-tags-plugin

pnpm add html-webpack-tags-plugin

Imports

HtmlWebpackTagsPlugin

wrong

const HtmlWebpackTagsPlugin = require('html-webpack-tags-plugin').default;

correct

import HtmlWebpackTagsPlugin from 'html-webpack-tags-plugin';

Plugin has a default export. In CommonJS, use require('html-webpack-tags-plugin').default.

HtmlWebpackTagsPlugin

wrong

import { HtmlWebpackTagsPlugin } from 'html-webpack-tags-plugin';

correct

const HtmlWebpackTagsPlugin = require('html-webpack-tags-plugin');

The plugin is a default export, not a named export. Named import will be undefined.

PluginOptions
```
import type { PluginOptions } from 'html-webpack-tags-plugin';
```
TypeScript users can import the options type for type-checking plugin configuration.

Quickstart

Shows how to configure HtmlWebpackTagsPlugin with external scripts, local CSS, and a meta tag, with append mode and public path enabled.

// webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin');
const HtmlWebpackTagsPlugin = require('html-webpack-tags-plugin').default;

module.exports = {
  plugins: [
    new HtmlWebpackPlugin(),
    new HtmlWebpackTagsPlugin({
      tags: [
        { tagName: 'script', path: 'https://example.com/external.js', attributes: { async: true } },
        { tagName: 'link', path: 'styles/custom.css', attributes: { rel: 'stylesheet' } },
        { tagName: 'meta', attributes: { name: 'description', content: 'My app' } }
      ],
      append: true,
      publicPath: true
    })
  ]
};