unplugin-vue

library7.1.1jsnpmunverified

unplugin-vue is a versatile utility designed to transform Vue 3 Single File Components (SFCs) into executable JavaScript across various build tools. Currently stable at version 7.1.1, it sees regular updates, often with weekly or bi-weekly bug fixes and minor feature enhancements, mirroring its close ties to the @vitejs/plugin-vue codebase. Its core strength lies in its "unplugin" architecture, enabling a single plugin to integrate seamlessly with Vite, Webpack, Rollup, esbuild, Rspack, Farm, and Rolldown. This broad compatibility differentiates it significantly from bundler-specific alternatives. It fully supports modern Vue features like <script setup> and component macros, and notably provides Hot Module Replacement (HMR) for Vite-based projects. Developers leverage it to process .vue files, making it an essential part of the Vue 3 development ecosystem for cross-platform build environments.

web-framework

npm install unplugin-vue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNPLUGIN-VUE

unplugin-vue

web-frameworkjavascriptv7.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Vue

✓ import Vue from 'unplugin-vue/vite'

✗ import { Vue } from 'unplugin-vue/vite'

For Vite integration, the plugin is typically imported as a default export from the bundler-specific path. This applies to Rollup, esbuild, Webpack, Rspack, Rolldown, and Farm as well, but with their respective path suffixes.

Vue

✓ import Vue from 'unplugin-vue/esbuild'

✗ const Vue = require('unplugin-vue/esbuild')

While esbuild configs can be JS, this package ships ESM and TypeScript types. Using `import` is recommended. CommonJS `require` might work via interop but is not the idiomatic approach for modern plugin configurations.

Vue

✓ import Vue from 'unplugin-vue/webpack'

✗ import { default as Vue } from 'unplugin-vue/webpack'

When configuring Webpack, Rspack, or Farm, ensure you're using the correct bundler-specific import path. The plugin is always a default export for direct consumption by the bundler's plugin array.

Illustrates how to integrate `unplugin-vue` into a Vite project for processing Vue 3 Single File Components.

import { defineConfig } from 'vite'; import Vue from 'unplugin-vue/vite'; export default defineConfig({ plugins: [ Vue({ /* options */ }), ], // Example of a basic Vue component (src/App.vue) // <template> // <div>Hello, Vue!</div> // </template> // <script setup> // import { ref } from 'vue'; // const msg = ref('World'); // </script> // <style scoped> // div { color: blue; } // </style> });

Debug

Known issues

gotchaHot Module Replacement (HMR) is currently not supported when using `unplugin-vue` with Webpack, Vue CLI, or Rspack. HMR is fully functional only for Vite environments.

fix

Consider using Vite for projects where HMR is critical, or be aware of manual page reloads when developing with unsupported bundlers.

affects: >=1.0.0

breaking`unplugin-vue` requires Node.js version 20.19.0 or higher. Older Node.js versions will result in installation or runtime errors.

fix

Upgrade your Node.js environment to version 20.19.0 or newer. Use a Node Version Manager (e.g., nvm) for easy switching.

affects: >=7.0.0

gotchaThe package has a peer dependency on `vue` at `^3.2.25`. Ensure your project's `vue` version meets this requirement to avoid potential conflicts or unexpected behavior during SFC compilation.

fix

Verify and update your `vue` dependency in `package.json` to a compatible version (e.g., `vue@latest`). Run `npm install` or `yarn install` afterwards.

affects: >=1.0.0

breakingBreaking changes and new features in `@vitejs/plugin-vue` are periodically synced into `unplugin-vue`. This means that upgrading `unplugin-vue` might implicitly introduce breaking changes from upstream, even if not explicitly listed in its own changelog.

fix

Always review the changelogs for both `unplugin-vue` and `@vitejs/plugin-vue` when performing major or minor upgrades to anticipate potential issues.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , unplugin_vue_vite__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

Attempting to import the plugin as a named export (`import { Vue } from '...'`) when it's provided as a default export.

fix

Change your import statement to `import Vue from 'unplugin-vue/vite'` (or the relevant bundler path) to correctly import the default export.

Error: Cannot find module 'unplugin-vue/vite' or its corresponding type declarations.

The package is not installed, or an incorrect bundler-specific path is used (e.g., 'unplugin-vue/vite' when using Webpack), or missing TypeScript types.

fix

Ensure `unplugin-vue` is installed (`npm i -D unplugin-vue`) and you are using the correct import path for your build tool (e.g., `unplugin-vue/webpack` for Webpack, `unplugin-vue/rollup` for Rollup).

Error: [unplugin-vue] Missing peer dependency "vue@^3.2.25"

The project's `vue` version does not satisfy the `unplugin-vue` peer dependency requirements.

fix

Install a compatible version of Vue 3: `npm install vue@latest` or specifically `npm install vue@3.x.x` that matches the peer dependency range.

Upgrade

Version history

7.1.1latest on npm

Audit

Dependencies

vuerequiredPeer dependency for Vue 3 SFC parsing and transformation.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/unplugin/unplugin-vue ↗

packagehttps://www.npmjs.com/package/unplugin-vue ↗

homepagehttps://unplugin.unjs.io/ ↗