Narcissistic, Perfectly Modest
    Have ideas to improve npm?Join in the discussion! »

    html-loader

    2.1.2 • Public • Published

    npm node deps tests coverage chat size

    html-loader

    Exports HTML as string. HTML is minimized when the compiler demands.

    Getting Started

    To begin, you'll need to install html-loader:

    npm install --save-dev html-loader

    Then add the plugin to your webpack config. For example:

    file.js

    import html from './file.html';

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
          },
        ],
      },
    };

    Options

    Name Type Default Description
    sources {Boolean|Object} true Enables/Disables sources handling
    preprocessor {Function} undefined Allows pre-processing of content before handling
    minimize {Boolean|Object} true in production mode, otherwise false Tell html-loader to minimize HTML
    esModule {Boolean} true Enable/disable ES modules syntax

    sources

    Type: Boolean|Object Default: true

    By default every loadable attributes (for example - <img src="image.png">) is imported (const img = require('./image.png') or import img from "./image.png""). You may need to specify loaders for images in your configuration (recommended asset modules).

    Supported tags and attributes:

    • the src attribute of the audio tag
    • the src attribute of the embed tag
    • the src attribute of the img tag
    • the srcset attribute of the img tag
    • the src attribute of the input tag
    • the data attribute of the object tag
    • the src attribute of the script tag
    • the href attribute of the script tag
    • the xlink:href attribute of the script tag
    • the src attribute of the source tag
    • the srcset attribute of the source tag
    • the src attribute of the track tag
    • the poster attribute of the video tag
    • the src attribute of the video tag
    • the xlink:href attribute of the image tag
    • the href attribute of the image tag
    • the xlink:href attribute of the use tag
    • the href attribute of the use tag
    • the href attribute of the link tag when the rel attribute contains stylesheet, icon, shortcut icon, mask-icon, apple-touch-icon, apple-touch-icon-precomposed, apple-touch-startup-image, manifest, prefetch, preload or when the itemprop attribute is image, logo, screenshot, thumbnailurl, contenturl, downloadurl, duringmedia, embedurl, installurl, layoutimage
    • the imagesrcset attribute of the link tag when the rel attribute contains stylesheet, icon, shortcut icon, mask-icon, apple-touch-icon, apple-touch-icon-precomposed, apple-touch-startup-image, manifest, prefetch, preload
    • the content attribute of the meta tag when the name attribute is msapplication-tileimage, msapplication-square70x70logo, msapplication-square150x150logo, msapplication-wide310x150logo, msapplication-square310x310logo, msapplication-config, twitter:image or when the property attribute is og:image, og:image:url, og:image:secure_url, og:audio, og:audio:secure_url, og:video, og:video:secure_url, vk:image or when the itemprop attribute is image, logo, screenshot, thumbnailurl, contenturl, downloadurl, duringmedia, embedurl, installurl, layoutimage
    • the icon-uri value component in content attribute of the meta tag when the name attribute is msapplication-task

    Boolean

    The true value enables processing of all default elements and attributes, the false disable processing of all attributes.

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              // Disables attributes processing
              sources: false,
            },
          },
        ],
      },
    };

    Object

    Allows you to specify which tags and attributes to process, filter them, filter urls and process sources starts with /.

    For example:

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              sources: {
                list: [
                  // All default supported tags and attributes
                  '...',
                  {
                    tag: 'img',
                    attribute: 'data-src',
                    type: 'src',
                  },
                  {
                    tag: 'img',
                    attribute: 'data-srcset',
                    type: 'srcset',
                  },
                ],
                urlFilter: (attribute, value, resourcePath) => {
                  // The `attribute` argument contains a name of the HTML attribute.
                  // The `value` argument contains a value of the HTML attribute.
                  // The `resourcePath` argument contains a path to the loaded HTML file.
    
                  if (/example\.pdf$/.test(value)) {
                    return false;
                  }
    
                  return true;
                },
              },
            },
          },
        ],
      },
    };

    list

    Type: Array Default: supported tags and attributes.

    Allows to setup which tags and attributes to process and how, and the ability to filter some of them.

    Using ... syntax allows you to extend default supported tags and attributes.

    For example:

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              sources: {
                list: [
                  // All default supported tags and attributes
                  '...',
                  {
                    tag: 'img',
                    attribute: 'data-src',
                    type: 'src',
                  },
                  {
                    tag: 'img',
                    attribute: 'data-srcset',
                    type: 'srcset',
                  },
                  {
                    // Tag name
                    tag: 'link',
                    // Attribute name
                    attribute: 'href',
                    // Type of processing, can be `src` or `scrset`
                    type: 'src',
                    // Allow to filter some attributes
                    filter: (tag, attribute, attributes, resourcePath) => {
                      // The `tag` argument contains a name of the HTML tag.
                      // The `attribute` argument contains a name of the HTML attribute.
                      // The `attributes` argument contains all attributes of the tag.
                      // The `resourcePath` argument contains a path to the loaded HTML file.
    
                      if (/my-html\.html$/.test(resourcePath)) {
                        return false;
                      }
    
                      if (!/stylesheet/i.test(attributes.rel)) {
                        return false;
                      }
    
                      if (
                        attributes.type &&
                        attributes.type.trim().toLowerCase() !== 'text/css'
                      ) {
                        return false;
                      }
    
                      return true;
                    },
                  },
                ],
              },
            },
          },
        ],
      },
    };

    If the tag name is not specified it will process all the tags.

    You can use your custom filter to specify html elements to be processed.

    For example:

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              sources: {
                list: [
                  {
                    // Attribute name
                    attribute: 'src',
                    // Type of processing, can be `src` or `scrset`
                    type: 'src',
                    // Allow to filter some attributes (optional)
                    filter: (tag, attribute, attributes, resourcePath) => {
                      // The `tag` argument contains a name of the HTML tag.
                      // The `attribute` argument contains a name of the HTML attribute.
                      // The `attributes` argument contains all attributes of the tag.
                      // The `resourcePath` argument contains a path to the loaded HTML file.
    
                      // choose all HTML tags except img tag
                      return tag.toLowerCase() !== 'img';
                    },
                  },
                ],
              },
            },
          },
        ],
      },
    };

    Filter can also be used to extend the supported elements and attributes.

    For example, filter can help process meta tags that reference assets:

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              sources: {
                list: [
                  {
                    tag: 'meta',
                    attribute: 'content',
                    type: 'src',
                    filter: (tag, attribute, attributes, resourcePath) => {
                      if (
                        attributes.value === 'og:image' ||
                        attributes.name === 'twitter:image'
                      ) {
                        return true;
                      }
    
                      return false;
                    },
                  },
                ],
              },
            },
          },
        ],
      },
    };

    Note: source with a tag option takes precedence over source without.

    Filter can be used to disable default sources.

    For example:

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              sources: {
                list: [
                  '...',
                  {
                    tag: 'img',
                    attribute: 'src',
                    type: 'src',
                    filter: () => false,
                  },
                ],
              },
            },
          },
        ],
      },
    };

    urlFilter

    Type: Function Default: undefined

    Allow to filter urls. All filtered urls will not be resolved (left in the code as they were written). All non requestable sources (for example <img src="javascript:void(0)">) do not handle by default.

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              sources: {
                urlFilter: (attribute, value, resourcePath) => {
                  // The `attribute` argument contains a name of the HTML attribute.
                  // The `value` argument contains a value of the HTML attribute.
                  // The `resourcePath` argument contains a path to the loaded HTML file.
    
                  if (/example\.pdf$/.test(value)) {
                    return false;
                  }
    
                  return true;
                },
              },
            },
          },
        ],
      },
    };

    preprocessor

    Type: Function Default: undefined

    Allows pre-processing of content before handling.

    You should always return valid HTML

    file.hbs

    <div>
      <p>{{firstname}} {{lastname}}</p>
      <img src="image.png" alt="alt" />
    <div>

    Function

    You can set the preprocessor option as a Function instance.

    webpack.config.js

    const Handlebars = require('handlebars');
    
    module.exports = {
      module: {
        rules: [
          {
            test: /\.hbs$/i,
            loader: 'html-loader',
            options: {
              preprocessor: (content, loaderContext) => {
                let result;
    
                try {
                  result = Handlebars.compile(content)({
                    firstname: 'Value',
                    lastname: 'OtherValue',
                  });
                } catch (error) {
                  loaderContext.emitError(error);
    
                  return content;
                }
    
                return result;
              },
            },
          },
        ],
      },
    };

    You can also set the preprocessor option as an asynchronous function instance.

    For example:

    webpack.config.js

    const Handlebars = require('handlebars');
    
    module.exports = {
      module: {
        rules: [
          {
            test: /\.hbs$/i,
            loader: 'html-loader',
            options: {
              preprocessor: async (content, loaderContext) => {
                let result;
    
                try {
                  result = await Handlebars.compile(content)({
                    firstname: 'Value',
                    lastname: 'OtherValue',
                  });
                } catch (error) {
                  await loaderContext.emitError(error);
    
                  return content;
                }
    
                return result;
              },
            },
          },
        ],
      },
    };

    minimize

    Type: Boolean|Object Default: true in production mode, otherwise false

    Tell html-loader to minimize HTML.

    Boolean

    The enabled rules for minimizing by default are the following ones:

    ({
      caseSensitive: true,
      collapseWhitespace: true,
      conservativeCollapse: true,
      keepClosingSlash: true,
      minifyCSS: true,
      minifyJS: true,
      removeComments: true,
      removeRedundantAttributes: true,
      removeScriptTypeAttributes: true,
      removeStyleLinkTypeAttributes: true,
    });

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              minimize: true,
            },
          },
        ],
      },
    };

    Object

    webpack.config.js

    See html-minifier-terser's documentation for more information on the available options.

    The rules can be disabled using the following options in your webpack.conf.js

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              minimize: {
                removeComments: false,
                collapseWhitespace: false,
              },
            },
          },
        ],
      },
    };

    esModule

    Type: Boolean Default: true

    By default, html-loader generates JS modules that use the ES modules syntax. There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.

    You can enable a CommonJS modules syntax using:

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {
              esModule: false,
            },
          },
        ],
      },
    };

    Examples

    Disable url resolving using the <!-- webpackIgnore: true --> comment

    With <!-- webpackIgnore: true --> comment, can to disable sources handling for next tag.

    <!-- Disabled url handling for the src attribute -->
    <!-- webpackIgnore: true -->
    <img src="image.png" />
    
    <!-- Disabled url handling for the src and srcset attributes -->
    <!-- webpackIgnore: true -->
    <img
      srcset="image.png 480w, image.png 768w"
      src="image.png"
      alt="Elva dressed as a fairy"
    />
    
    <!-- Disabled url handling for the content attribute -->
    <!-- webpackIgnore: true -->
    <meta itemprop="image" content="./image.png" />
    
    <!-- Disabled url handling for the href attribute -->
    <!-- webpackIgnore: true -->
    <link rel="icon" type="image/png" sizes="192x192" href="./image.png" />

    roots

    With resolve.roots can specify a list of directories where requests of server-relative URLs (starting with '/') are resolved.

    webpack.config.js

    module.exports = {
      context: __dirname,
      module: {
        rules: [
          {
            test: /\.html$/i,
            loader: 'html-loader',
            options: {},
          },
          {
            test: /\.jpg$/,
            type: 'asset/resource',
          },
        ],
      },
      resolve: {
        roots: [path.resolve(__dirname, 'fixtures')],
      },
    };

    file.html

    <img src="/image.jpg" />
    // => image.jpg in __dirname/fixtures will be resolved

    CDN

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.jpg$/,
            type: 'asset/resource',
          },
          {
            test: /\.png$/,
            type: 'asset/inline',
          },
        ],
      },
      output: {
        publicPath: 'http://cdn.example.com/[fullhash]/',
      },
    };

    file.html

    <img src="image.jpg" data-src="image2x.png" />

    index.js

    require('html-loader!./file.html');
    
    // => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="image2x.png">'
    require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
    
    // => '<img src="image.jpg" data-src="data:image/png;base64,..." >'
    require('html-loader?{"sources":{"list":[{"tag":"img","attribute":"src","type":"src"},{"tag":"img","attribute":"data-src","type":"src"}]}}!./file.html');
    
    // => '<img src="http://cdn.example.com/49eba9f/a992ca.jpg" data-src="data:image/png;base64,..." >'

    Process script and link tags

    script.file.js

    console.log(document);

    style.file.css

    a {
      color: red;
    }

    file.html

    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8" />
        <title>Title of the document</title>
        <link rel="stylesheet" type="text/css" href="./style.file.css" />
      </head>
      <body>
        Content of the document......
        <script src="./script.file.js"></script>
      </body>
    </html>

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.html$/,
            type: 'asset/resource',
            generator: {
              filename: '[name][ext]',
            },
          },
          {
            test: /\.html$/i,
            use: ['extract-loader', 'html-loader'],
          },
          {
            test: /\.js$/i,
            exclude: /\.file.js$/i,
            loader: 'babel-loader',
          },
          {
            test: /\.file.js$/i,
            type: 'asset/resource',
          },
          {
            test: /\.css$/i,
            exclude: /\.file.css$/i,
            loader: 'css-loader',
          },
          {
            test: /\.file.css$/i,
            type: 'asset/resource',
          },
        ],
      },
    };

    Templating

    You can use any template system. Below is an example for handlebars.

    file.hbs

    <div>
      <p>{{firstname}} {{lastname}}</p>
      <img src="image.png" alt="alt" />
    <div>

    webpack.config.js

    const Handlebars = require('handlebars');
    
    module.exports = {
      module: {
        rules: [
          {
            test: /\.hbs$/i,
            loader: 'html-loader',
            options: {
              preprocessor: (content, loaderContext) => {
                let result;
    
                try {
                  result = Handlebars.compile(content)({
                    firstname: 'Value',
                    lastname: 'OtherValue',
                  });
                } catch (error) {
                  loaderContext.emitError(error);
    
                  return content;
                }
    
                return result;
              },
            },
          },
        ],
      },
    };

    PostHTML

    You can use PostHTML without any additional loaders.

    file.html

    <img src="image.jpg" />

    webpack.config.js

    const posthtml = require('posthtml');
    const posthtmlWebp = require('posthtml-webp');
    
    module.exports = {
      module: {
        rules: [
          {
            test: /\.hbs$/i,
            loader: 'html-loader',
            options: {
              preprocessor: (content, loaderContext) => {
                let result;
    
                try {
                  result = posthtml().use(plugin).process(content, { sync: true });
                } catch (error) {
                  loaderContext.emitError(error);
    
                  return content;
                }
    
                return result.html;
              },
            },
          },
        ],
      },
    };

    Export into HTML files

    A very common scenario is exporting the HTML into their own .html file, to serve them directly instead of injecting with javascript. This can be achieved with a combination of 2 loaders:

    and asset modules

    The html-loader will parse the URLs, require the images and everything you expect. The extract loader will parse the javascript back into a proper html file, ensuring images are required and point to proper path, and the asset modules will write the .html file for you. Example:

    webpack.config.js

    module.exports = {
      output: {
        assetModuleFilename: '[name][ext]',
      },
      module: {
        rules: [
          {
            test: /\.html$/,
            type: 'asset/resource',
            generator: {
              filename: '[name][ext]',
            },
          },
          {
            test: /\.html$/i,
            use: ['extract-loader', 'html-loader'],
          },
        ],
      },
    };

    Contributing

    Please take a moment to read our contributing guidelines if you haven't yet done so.

    CONTRIBUTING

    License

    MIT

    Install

    npm i html-loader

    DownloadsWeekly Downloads

    1,232,913

    Version

    2.1.2

    License

    MIT

    Unpacked Size

    77.7 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar