vue-template-loader

1.1.0 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader that pre-compiles Vue.js 2.0 HTML templates into render functions using vue-template-compiler. Current stable version is 1.1.0 (released June 2019) with low release cadence. Supports scoped CSS, CSS modules, HMR, and functional components. A lighter alternative to vue-loader when you only need template compilation. Note: requires vue-template-compiler as a peer dependency and is specifically for Vue 2 — incompatible with Vue 3.

Common errors

error Error: Cannot find module 'vue-template-compiler' ↓

cause Missing peer dependency vue-template-compiler.

fix

npm install vue-template-compiler --save-dev (ensure version matches your Vue version)

error Uncaught TypeError: template is not a function ↓

cause Using the imported module incorrectly; the default export is a function that injects render into component options.

fix

Use: const Component = withRender({ /* options */ });

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Webpack is not configured with vue-template-loader for .html files.

fix

Add rule: { test: /\.html$/, use: 'vue-template-loader' } to your webpack config.

error [Vue warn]: Failed to mount component: template or render function not defined. ↓

cause The loader did not inject a render function; possibly missing loader config or incorrect import path.

fix

Verify .html file is processed by vue-template-loader and import path is correct.

Warnings

breaking In v1.0.0, the `transformToRequire` option was renamed to `transformAssetUrls`. The old key will cause the option to be silently ignored. ↓

fix Replace `transformToRequire` with `transformAssetUrls` in loader options.

breaking v1.0.0 changed internal dependencies to @vue/component-compiler-utils, which may alter behavior for custom blocks or edge cases. ↓

fix Test your templates after upgrading. Ensure vue-template-compiler peer dependency matches Vue 2 version.

gotcha Scoped styles require query syntax `?style=./style.css` and post-loader configuration. Forgetting either will silently fail to apply scoped CSS. ↓

fix Use `import withRender from './template.html?style=./style.css'` and set `enforce: 'post'` on style loaders that should run after scope injection.

deprecated This package is primarily for Vue 2; no official support for Vue 3. Vue 3 users should use @vue/compiler-sfc and Vue Loader 16+. ↓

fix For Vue 3, migrate to vue-loader or use @vue/compiler-sfc directly.

gotcha When using functional components, the `functional: true` option must be set in the loader config. Using the loader without this option on a functional template will produce a runtime error. ↓

fix Add `options: { functional: true }` to the loader rule for functional templates. Use `oneOf` for mixed setups.

Install

npm install vue-template-loader

yarn add vue-template-loader

pnpm add vue-template-loader

Imports

export default function
wrong
```
const withRender = require('./template.html')
```
correct
```
import withRender from './template.html'
```
ESM default export imports the compiled render/inject function.

withRender (injected)

wrong

import withRender from './template.html'

correct

import withRender from './template.html?style=./style.css'

Use ?style= query to load scoped styles alongside the template.

webpack rule config

wrong

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

correct

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

Use `use` property for loader string; `loader` works but is less common in modern configs.

Quickstart

Shows basic webpack config, a Vue HTML template, and usage of the compiled render function to create a component.

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

// App.vue (if using single file components, otherwise just template.html)
// template.html
<template>
  <div>{{ message }}</div>
</template>

// main.js
import Vue from 'vue';
import withRender from './template.html';

const App = withRender({
  data() {
    return { message: 'Hello Vue!' };
  }
});

new Vue({
  render: h => h(App)
}).$mount('#app');