@vitejs/plugin-vue

@vitejs/plugin-vue is the officially maintained Vite plugin that compiles Vue 3 .vue Single File Components into JavaScript modules Vite can serve and bundle. It hooks into Vite’s plugin pipeline to parse each SFC into its script, template, and style blocks, run them through vue/compiler-sfc, and wire up hot module replacement so component edits update in the browser almost instantly while preserving local state.

It is the plugin create-vite scaffolds into every Vue project by default, and it underpins the dev experience for Vue apps built on Vite, VitePress, and other Vite-based tooling. Beyond baseline compilation it supports scoped and CSS Modules styles, custom SFC blocks (e.g. <i18n>), Vue’s Custom Elements mode, and the newer Vapor compilation mode, all configurable through a single Options object passed to the plugin factory.

What You Get

• A drop-in Vite plugin (plugins: [vue()]) that compiles .vue Single File Components with zero additional build configuration
• Fast, state-preserving HMR driven by handleHotUpdate, which diffs script/template/style blocks to avoid unnecessary full reloads
• Support for scoped CSS, CSS Modules, and custom SFC blocks (like <i18n>) via pluggable transform hooks
• Vue Custom Elements compilation mode (*.ce.vue) for shipping standalone web components with inlined styles
• Configurable script, template, and style passthrough options mapped directly onto vue/compiler-sfc’s compile APIs
• Experimental Vapor mode support for compiling SFCs without the Virtual DOM runtime (Vue 3.6+)

Common Use Cases

• Every new Vue 3 project scaffolded with npm create vite@latest -- --template vue or vue-ts, where the plugin is preconfigured
• Vue component libraries that need defineCustomElement support to ship as standalone custom elements
• SSR and static-site frameworks built on Vite (e.g. VitePress) that need .vue compilation for both client and server bundles
• Projects using custom SFC blocks (YAML/JSON <i18n> blocks, <docs> blocks) processed by companion transform plugins
• Teams tuning production bundle size by disabling Options API support or prod devtools/hydration-mismatch details via features

Under The Hood

Architecture — The plugin’s entry point (src/index.ts) returns a Vite Plugin<Api> object wiring resolveId, load, and transform hooks around a virtual-module scheme: a .vue file’s script, template, and style blocks are addressed as ?vue&type=script|template|style sub-requests. The main request path (transformMain in main.ts) parses the file into an SFCDescriptor via createDescriptor (backed by an LRU-style cache in utils/descriptorCache.ts), decides whether the template can be inlined into the script block (canInlineMain/isUseInlineTemplate), and stitches together the final module combining compiled script, template render function, and style/query imports, applying @jridgewell source-map remapping so devtools show original .vue source positions. handleHotUpdate.ts implements Vite’s HMR contract by diffing the previous and current SFCDescriptor (isEqualBlock, isOnlyTemplateChanged) to decide between template-only patches, style-only patches, or a full reload, and separately tracks TypeScript type-only dependencies (typeDepToSFCMap) so edits to imported .ts type files also trigger the right invalidation.

Tech Stack — Written in TypeScript (module type module), it delegates all actual Vue SFC parsing/compilation to vue/compiler-sfc (resolved dynamically per-project via resolveCompiler in compiler.ts to support version pinning), and depends on Vite’s own Plugin, Rollup.TransformPluginContext, and ModuleNode types for its hook signatures. Source-map composition uses @jridgewell/trace-mapping and @jridgewell/gen-mapping; module filtering uses @rolldown/pluginutils’ exactRegex/makeIdFiltersToMatchWithQuery helpers to scope the new Rolldown-aware filter API. It builds with tsdown to a single ESM entry (dist/index.mjs) and declares vite and vue as peer dependencies rather than bundling them, keeping the plugin thin and version-flexible within the monorepo’s pnpm catalog.

Code Quality — The package ships a small dedicated __tests__ unit-test file (Vapor-only-template handling) but the bulk of correctness is enforced by the monorepo’s 12+ Playwright-driven e2e suites under playground/ (vue, vue-jsx, vue-legacy, vue-lib, vue-custom-id, vue-asset-base, vue-sourcemap, ssr-vue, vue-server-origin, tailwind, tailwind-v3), each running real Vite dev servers and production builds against representative app fixtures and asserting on rendered output, HMR behavior, and generated assets. Source files are consistently typed against vue/compiler-sfc’s own types, deprecated options (customElements, script.propsDestructure) are kept working but marked @deprecated with migration comments rather than silently dropped, and the code enforces ESLint/oxfmt via pre-commit hooks (simple-git-hooks + lint-staged).

API Design — The public surface is a single default export, a factory function vuePlugin(options?: Options): Plugin<Api>, so adopting it is one line in vite.config.js. The Options interface groups configuration by concern (script, template, style map directly onto vue/compiler-sfc compile options; features groups newer toggles like propsDestructure, customElement, vapor, optionsAPI) and the plugin exposes a typed Api object (options, include, exclude, version) so other plugins in a chain can introspect or adjust its behavior. Deprecated top-level options are retained with clear @deprecated JSDoc pointing to their features.* replacement, minimizing breaking changes across major versions.