vuetify-loader (Vuetify 2)

1.9.2 verified Sat Apr 25 auth: no javascript maintenance

Vuetify-loader is a Webpack plugin that enables automatic tree-shaking and on-demand imports of Vuetify 2 components, reducing bundle size. It also supports progressive image loading with low-res placeholders. Current stable version is 1.9.2, released 2022-08-10, with maintenance mode only as Vuetify 3 is now available. Key differentiators: auto-imports components used in templates, supports custom match functions for project components, and integrates with Vue CLI. Requires Vue 2.7+, Vuetify 2.x, and Webpack 4/5. Not compatible with Vuetify 3 (use vuetify-loader v2+).

Common errors

error Module not found: Error: Can't resolve 'vuetify-loader' ↓

cause vuetify-loader is not installed or typo in package name.

fix

Run: npm install vuetify-loader --save-dev, and ensure import path is correct.

error TypeError: VuetifyLoaderPlugin is not a constructor ↓

cause Default import used instead of named destructured import.

fix

Use: const { VuetifyLoaderPlugin } = require('vuetify-loader');

error ERROR in ./src/App.vue?vue&type=style&index=0&lang=css Module build failed (from ./node_modules/vue-loader/lib/index.js): TypeError: Cannot read property 'match' of undefined ↓

cause VueLoaderPlugin is missing or misconfigured. vuetify-loader relies on vue-loader rules.

fix

Add new VueLoaderPlugin() to webpack plugins before VuetifyLoaderPlugin.

error WARNING in configuration The 'mode' option has not been set, webpack will fallback to 'production' for this value. Set 'mode' option to 'development' or 'production' to enable defaults for each environment. ↓

cause Webpack config lacks mode; this is a generic warning but can cause confusion when vuetify-loader behaves differently in dev vs prod.

fix

Add mode: 'production' or mode: 'development' to your webpack config.

error Error: Child compilation failed: Module not found: Error: Can't resolve 'vuetify/lib' ↓

cause Vuetify 3 installed but using vuetify-loader v1 which expects Vuetify 2 path structure.

fix

Install Vuetify 2 (npm i vuetify@^2) or use vuetify-loader@next for Vuetify 3.

Warnings

breaking Vuetify 3 is not supported by vuetify-loader v1.x. Use vuetify-loader v2 (next branch) for Vuetify 3. ↓

fix Upgrade to vuetify-loader@next for Vuetify 3, or stay on v1.x for Vuetify 2.

deprecated VuetifyLoaderPlugin is deprecated as of Vuetify 3; use webpack-plugin-vuetify from the next branch instead. ↓

fix For Vuetify 3 projects, install webpack-plugin-vuetify and follow its documentation.

gotcha Progressive images require one of graphicsmagick, imagemagick, or sharp to be installed on the system. Missing dependency results in no placeholder generation and no error. ↓

fix Install sharp (npm i sharp -D) or ensure gm/imagemagick is available in PATH.

breaking Vue 2.7 is required for v1.9.0+. Earlier versions of vuetify-loader (<1.9.0) do not support Vue 2.7. ↓

fix Upgrade Vue to ^2.7.2 or use vuetify-loader@1.8.x if stuck on Vue 2.6.

gotcha The 'match' function must return an array of two elements: [camelTag, importString]. Returning undefined/null is ignored; returning a malformed array breaks compilation. ↓

fix Ensure match returns [camelTag, `import ${camelTag} from '...'`] or undefined.

gotcha ResourceQuery for progressive images only works with static paths. Dynamic paths (e.g., :src="imagePath") must use require() with ?vuetify-preload query. ↓

fix Use require(`@/assets/${dynamic}.jpg?vuetify-preload`) inside the template for dynamic images.

Install

npm install vuetify-loader

yarn add vuetify-loader

pnpm add vuetify-loader

Imports

VuetifyLoaderPlugin
wrong
```
const VuetifyLoaderPlugin = require('vuetify-loader')
```
correct
```
const { VuetifyLoaderPlugin } = require('vuetify-loader')
```
Default export is not available; must destructure named export. CommonJS is the standard as this is a Webpack plugin.
VuetifyLoaderPlugin (ESM)
wrong
```
import VuetifyLoaderPlugin from 'vuetify-loader'
```
correct
```
import { VuetifyLoaderPlugin } from 'vuetify-loader'
```
When using ESM in your Webpack config (e.g., with .mjs), import the named export. Default import is undefined.
VuetifyLoaderPlugin via Vue CLI chainWebpack
wrong
```
config.plugin('VuetifyLoaderPlugin').use(VuetifyLoaderPlugin, [options])
```
correct
```
config.plugin('VuetifyLoaderPlugin').use(require('vuetify-loader').VuetifyLoaderPlugin, [options])
```
In vue.config.js, you must require the plugin inside the chainWebpack function. Direct reference to imported variable may fail due to module scope.

Quickstart

Shows minimal Webpack 4/5 configuration with vuetify-loader, including VueLoaderPlugin and progressiveImages option.

// webpack.config.js
const { VuetifyLoaderPlugin } = require('vuetify-loader');
const Vuetify = require('vuetify');
const VueLoaderPlugin = require('vue-loader/lib/plugin');

module.exports = {
  entry: './src/main.js',
  output: { filename: 'bundle.js' },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      }
    ]
  },
  plugins: [
    new VueLoaderPlugin(),
    new VuetifyLoaderPlugin({
      progressiveImages: true
    })
  ]
};