Vue HTML Loader

Common errors

• Module build failed: Error: Cannot find module 'vue-html-loader'

  cause The `vue-html-loader` package has not been installed or is not resolvable in your project.
  fix Run `npm install --save-dev vue-html-loader` or `yarn add -D vue-html-loader` to install the package.

• Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file.

  cause Webpack is encountering an HTML file but does not have `vue-html-loader` or `html-loader` configured in its rules to process it.
  fix Add a rule to your `webpack.config.js` to handle HTML files using `vue-html-loader`: `{ test: /\.html$/, use: 'vue-html-loader' }`.

• Assets referenced in HTML (e.g., <img> src) are not being resolved or result in broken paths.

  cause `vue-html-loader` processes asset paths, but the necessary subsequent loaders (like `file-loader` or `url-loader`) or Webpack 5 Asset Modules for handling those assets are missing or misconfigured.
  fix Ensure your `webpack.config.js` includes rules for image files (e.g., `test: /\.(png|jpe?g|gif|svg)$/i`) with `file-loader`, `url-loader`, or Webpack 5's built-in Asset Modules (`type: 'asset/resource'`). Also, check the `attrs` option for `vue-html-loader` to ensure it's configured to process the relevant tag-attribute combinations.

Warnings

• breaking This package is explicitly abandoned and has not been updated since 2016. It is severely outdated and will not be compatible with modern Webpack versions (v4, v5, or v6) or Vue.js versions (Vue 2 with `vue-loader` v15+, Vue 3, Vue CLI, or Vite). Using it in new projects or upgrading existing ones is highly discouraged.
  Fix: Migrate to `vue-loader` for processing `.vue` Single File Components or use `html-loader` (with appropriate configuration) for general HTML files in modern Webpack projects. For Vue 3, consider Vite as a build tool.
• gotcha Due to its age, `vue-html-loader` might lack features or have incompatible syntax compared to current Webpack loader options. Configuration methods (like query strings vs. `options` object) have evolved significantly in Webpack.
  Fix: If migrating from an extremely old Webpack setup, carefully review Webpack's documentation for loader options and syntax changes. It's generally better to migrate away from this loader entirely.
• breaking Webpack 5 introduced Asset Modules, which supersede `file-loader`, `url-loader`, and `raw-loader`. `vue-html-loader` was designed to work with these older loaders for asset handling, meaning direct migration to Webpack 5's asset modules may break its functionality.
  Fix: For new projects, use Webpack 5's built-in Asset Modules (`type: 'asset/resource'`, `type: 'asset/inline'`) instead of `file-loader` or `url-loader`. For legacy projects, consider maintaining older Webpack versions or rewriting asset handling.
• gotcha The loader relies on correct setup of other loaders (e.g., `file-loader` or `url-loader`) for asset processing (e.g., `<img src="image.png">`). If these are not configured or are incompatible, image paths will not be resolved correctly.
  Fix: Ensure `file-loader` or `url-loader` (or Webpack 5 Asset Modules for newer projects) are properly configured in `webpack.config.js` for the asset types referenced in your HTML templates.

Install

• npm install vue-html-loader npm
• yarn add vue-html-loader yarn
• pnpm add vue-html-loader pnpm

Imports

• module.rules.use
  wrong:

  import VueHtmlLoader from 'vue-html-loader';

  correct:

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

  This package is a Webpack loader and is configured within `webpack.config.js` via the `module.rules` array, not imported into application code. Ensure it's correctly listed in the `use` array for HTML files.
• vue.html (options)
  wrong:

  module.exports = { htmlLoader: { /* options */ } }

  correct:

  module.exports = { vue: { html: { /* loader options */ } } }

  Loader-specific options for `vue-html-loader` are traditionally nested under the `vue.html` property in the Webpack configuration for older Vue Loader setups. For modern Webpack, options would typically be passed directly to the loader in the `use` array.
• attrs (query parameter)
  wrong:

  { test: /\.html$/, use: 'vue-html-loader?attrs=img.src' }

  correct:

  { test: /\.html$/, use: 'vue-html-loader?attrs[]=img:src&attrs[]=img:data-src' }

  The `attrs` query parameter accepts a space-separated string or an array of `<tag>:<attribute>` combinations to process. Use `attrs=false` to disable all attribute processing.

Quickstart

This `webpack.config.js` snippet demonstrates how to configure `vue-html-loader` to process HTML files, resolve image assets using `file-loader`, and enable optional HTML minimization. It shows both direct loader usage and older `vue` config block options.

const path = require('path');

module.exports = {
  entry: './src/main.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.html$/,
        use: ['vue-html-loader?root=.', 'html-loader'], // Chaining with html-loader might be necessary for some features
        exclude: /index.html/ // Typically exclude main index.html if using HtmlWebpackPlugin
      },
      {
        test: /\.(png|jpe?g|gif|svg)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[name].[hash].[ext]',
              outputPath: 'assets/images',
            },
          },
        ],
      },
      // Note: For actual Vue SFCs, you would use vue-loader and vue-template-compiler
      // This example focuses on standalone HTML templates processed by vue-html-loader
    ]
  },
  // Example of vue-html-loader specific options (older Webpack config style)
  vue: {
    html: {
      minimize: true, // Example: Enable HTML minimization
      // Other options like 'attrs' can be specified here as well for older configs
      // e.g., attrs: ['img:src', 'img:data-src']
    }
  },
  // Ensure Webpack 5 Asset Modules are handled correctly alongside older loaders
  // For Webpack 5, it's generally recommended to use built-in Asset Modules instead of file-loader/url-loader
  // However, for compatibility with vue-html-loader, older loaders might be required.
};