Unplugin Vue 3 SFC Transformer

Common errors

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

  cause 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.

  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.
  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"

  cause 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.

Warnings

• gotcha 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.
  Fix: Consider using Vite for projects where HMR is critical, or be aware of manual page reloads when developing with unsupported bundlers.
• 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.
• gotcha 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.
  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.
• breaking 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.
  Fix: Always review the changelogs for both `unplugin-vue` and `@vitejs/plugin-vue` when performing major or minor upgrades to anticipate potential issues.

Install

• npm install unplugin-vue npm
• yarn add unplugin-vue yarn
• pnpm add unplugin-vue pnpm

Imports

• Vue
  wrong:

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

  correct:

  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
  wrong:

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

  correct:

  import Vue from '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
  wrong:

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

  correct:

  import 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.

Quickstart

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>
});