@yued/html-loader

    0.5.5 • Public • Published

    npm deps test coverage chat

    HTML Loader

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

    Install

    npm i -D html-loader

    Usage

    By default every local <img src="image.png"> is required (require('./image.png')). You may need to specify loaders for images in your configuration (recommended file-loader or url-loader).

    You can specify which tag-attribute combination should be processed by this loader via the query parameter attrs. Pass an array or a space-separated list of <tag>:<attribute> combinations. (Default: attrs=img:src)

    If you use <custom-elements>, and lots of them make use of a custom-src attribute, you don't have to specify each combination <tag>:<attribute>: just specify an empty tag like attrs=:custom-src and it will match every element.

    {
      test: /\.(html)$/,
      use: {
        loader: 'html-loader',
        options: {
          attrs: [':data-src']
        }
      }
    }

    To completely disable tag-attribute processing (for instance, if you're handling image loading on the client side) you can pass in attrs=false.

    Examples

    With this configuration:

    {
      module: {
        rules: [
          { test: /\.jpg$/, use: [ "file-loader" ] },
          { test: /\.png$/, use: [ "url-loader?mimetype=image/png" ] }
        ]
      },
      output: {
        publicPath: "http://cdn.example.com/[hash]/"
      }
    }
    <!-- file.html -->
    <img src="image.png" data-src="image2x.png" >
    require("html-loader!./file.html");
     
    // => '<img src="http://cdn.example.com/49eba9f/a992ca.png"
    //         data-src="image2x.png">'
    require("html-loader?attrs=img:data-src!./file.html");
     
    // => '<img src="image.png" data-src="data:image/png;base64,..." >'
    require("html-loader?attrs=img:src img:data-src!./file.html");
    require("html-loader?attrs[]=img:src&attrs[]=img:data-src!./file.html");
     
    // => '<img  src="http://cdn.example.com/49eba9f/a992ca.png"        
    //           data-src="data:image/png;base64,..." >'
    require("html-loader?-attrs!./file.html");
     
    // => '<img  src="image.jpg"  data-src="image2x.png" >'

    minimized by running webpack --optimize-minimize

    '<img src=http://cdn.example.com/49eba9f/a9f92ca.jpg
          data-src=data:image/png;base64,...>'

    or specify the minimize property in the rule's options in your webpack.conf.js

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

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

    • removeComments
    • removeCommentsFromCDATA
    • removeCDATASectionsFromCDATA
    • collapseWhitespace
    • conservativeCollapse
    • removeAttributeQuotes
    • useShortDoctype
    • keepClosingSlash
    • minifyJS
    • minifyCSS
    • removeScriptTypeAttributes
    • removeStyleTypeAttributes

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

    module: {
      rules: [{
        test: /\.html$/,
        use: [ {
          loader: 'html-loader',
          options: {
            minimize: true,
            removeComments: false,
            collapseWhitespace: false
          }
        }],
      }]
    }

    'Root-relative' URLs

    For urls that start with a /, the default behavior is to not translate them. If a root query parameter is set, however, it will be prepended to the url and then translated.

    With the same configuration as above:

    <!-- file.html -->
    <img src="/image.jpg">
    require("html-loader!./file.html");
     
    // => '<img  src="/image.jpg">'
    require("html-loader?root=.!./file.html");
     
    // => '<img  src="http://cdn.example.com/49eba9f/a992ca.jpg">'

    Interpolation

    You can use interpolate flag to enable interpolation syntax for ES6 template strings, like so:

    require("html-loader?interpolate!./file.html");
    <img src="${require(`./images/gallery.png`)}">
     
    <div>${require('./components/gallery.html')}</div>

    And if you only want to use require in template and any other ${} are not to be translated, you can set interpolate flag to require, like so:

    require("html-loader?interpolate=require!./file.ftl");
     
    <#list list as list>
      <a href="${list.href!}" />${list.name}</a>
    </#list>
     
    <img src="${require(`./images/gallery.png`)}">
     
    <div>${require('./components/gallery.html')}</div>

    Export formats

    There are different export formats available:

    • module.exports (default, cjs format). "Hello world" becomes module.exports = "Hello world";
    • exports.default (when exportAsDefault param is set, es6to5 format). "Hello world" becomes exports.default = "Hello world";
    • export default (when exportAsEs6Default param is set, es6 format). "Hello world" becomes export default "Hello world";

    Advanced options

    If you need to pass more advanced options, especially those which cannot be stringified, you can also define an htmlLoader-property on your webpack.config.js:

    var path = require('path')
     
    module.exports = {
      ...
      module: {
        rules: [
          {
            test: /\.html$/,
            use: [ "html-loader" ]
          }
        ]
      },
      htmlLoader: {
        ignoreCustomFragments: [/\{\{.*?}}/],
        root: path.resolve(__dirname, 'assets'),
        attrs: ['img:src', 'link:href']
      }
    };

    If you need to define two different loader configs, you can also change the config's property name via html-loader?config=otherHtmlLoaderConfig:

    module.exports = {
      ...
      module: {
        rules: [
          {
            test: /\.html$/,
            use: [ "html-loader?config=otherHtmlLoaderConfig" ]
          }
        ]
      },
      otherHtmlLoaderConfig: {
        ...
      }
    };

    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 3 loaders:

    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 file loader will write the .html file for you. Example:

    {
      test: /\.html$/,
      use: [ 'file-loader?name=[path][name].[ext]!extract-loader!html-loader' ]
    }

    Maintainers


    Hemanth

    Joshua Wiens

    Michael Ciniawsky

    Imvetri

    Andrei Crnković

    Yuta Hiroto

    Vesselin Petrunov

    Gajus Kuizinas

    Keywords

    none

    Install

    npm i @yued/html-loader

    DownloadsWeekly Downloads

    4

    Version

    0.5.5

    License

    MIT

    Last publish

    Collaborators

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