{"id":12318,"library":"unplugin-vue","title":"Unplugin Vue 3 SFC Transformer","description":"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.","status":"active","version":"7.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/unplugin/unplugin-vue","tags":["javascript","vue","sfc","unplugin","vite","webpack","rollup","esbuild","typescript"],"install":[{"cmd":"npm install unplugin-vue","lang":"bash","label":"npm"},{"cmd":"yarn add unplugin-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add unplugin-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue 3 SFC parsing and transformation.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"import { Vue } from 'unplugin-vue/vite'","symbol":"Vue","correct":"import Vue from 'unplugin-vue/vite'"},{"note":"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.","wrong":"const Vue = require('unplugin-vue/esbuild')","symbol":"Vue","correct":"import Vue from 'unplugin-vue/esbuild'"},{"note":"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.","wrong":"import { default as Vue } from 'unplugin-vue/webpack'","symbol":"Vue","correct":"import Vue from 'unplugin-vue/webpack'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport Vue from 'unplugin-vue/vite';\n\nexport default defineConfig({\n  plugins: [\n    Vue({\n      /* options */\n    }),\n  ],\n  // Example of a basic Vue component (src/App.vue)\n  // <template>\n  //   <div>Hello, Vue!</div>\n  // </template>\n  // <script setup>\n  // import { ref } from 'vue';\n  // const msg = ref('World');\n  // </script>\n  // <style scoped>\n  // div { color: blue; }\n  // </style>\n});","lang":"typescript","description":"Illustrates how to integrate `unplugin-vue` into a Vite project for processing Vue 3 Single File Components."},"warnings":[{"fix":"Consider using Vite for projects where HMR is critical, or be aware of manual page reloads when developing with unsupported bundlers.","message":"Hot 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 20.19.0 or newer. Use a Node Version Manager (e.g., nvm) for easy switching.","message":"`unplugin-vue` requires Node.js version 20.19.0 or higher. Older Node.js versions will result in installation or runtime errors.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always review the changelogs for both `unplugin-vue` and `@vitejs/plugin-vue` when performing major or minor upgrades to anticipate potential issues.","message":"Breaking 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.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import Vue from 'unplugin-vue/vite'` (or the relevant bundler path) to correctly import the default export.","cause":"Attempting to import the plugin as a named export (`import { Vue } from '...'`) when it's provided as a default export.","error":"TypeError: (0 , unplugin_vue_vite__WEBPACK_IMPORTED_MODULE_0__.default) is not a function"},{"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).","cause":"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.","error":"Error: Cannot find module 'unplugin-vue/vite' or its corresponding type declarations."},{"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.","cause":"The project's `vue` version does not satisfy the `unplugin-vue` peer dependency requirements.","error":"Error: [unplugin-vue] Missing peer dependency \"vue@^3.2.25\""}],"ecosystem":"npm"}