@vizejs/vite-plugin

@vizejs/vite-plugin

High-performance native Vite plugin for Vue SFC compilation powered by Vize.

Features

• Native Performance: Uses Rust-based compiler via Node.js native bindings (NAPI)
• Pre-compilation: All .vue files are compiled at server startup for instant module resolution
• Virtual Modules: Compiled code is served from memory as virtual modules
• HMR Support: Hot Module Replacement with automatic re-compilation on file changes
• Vapor Mode: Optional support for Vue Vapor mode compilation

Installation

Install vp once from the Vite+ install guide, then add the packages:

vp install -D @vizejs/vite-plugin

Add vize as a direct dependency only if your project imports shared config helpers from "vize" (see Shared Config).

Usage

Vite+

Install the vite-plus version your project uses, then configure the whole toolchain:

// vite.config.ts
import { defineConfig } from "@vizejs/vite-plugin/vite-plus";

const vpConfig = {
  server: { port: 3000 },
};

export default defineConfig(vpConfig).withVue({
  compiler: { sourceMap: true },
  linter: { preset: "essential" },
  formatter: { singleQuote: true },
});

Run vp run check, lint, fmt, build, or pack without registering another plugin or writing CLI scripts. Native lint runs alongside Oxlint; overlapping rules and Vue formatting ownership are configured automatically.

Keep shared native settings in vue: using .withVue(vueConfig). Import ordinary JavaScript objects to reuse settings; custom config extends is no longer supported. Use pack.vue for native declarations, declaration maps, and compiler maps. The standalone withVue(vueConfig, vpConfig) helper remains available; it is not an alias of defineConfig(vpConfig). withVize is a compatibility name for the config-first helper. Prefer the fluent API for new configuration.

Vite+ remains a user-selected optional peer (0.2.3 or later); configuration types come from that peer. Ordinary Vite users do not need to install it. Built-in vp check/lint/fmt keep their Vite+ behavior; combined checks use vp run.

Run vp run editor:setup to recommend Vize alongside the Vite Plus extension pack while preserving existing workspace settings and Oxc's non-Vue formatter.

See the Vite+ guide and editor setup for configuration, task naming, native editor config, and tool ownership.

Vite

// vite.config.ts
import { defineConfig } from "vite";
import vize from "@vizejs/vite-plugin";

export default defineConfig({
  plugins: [
    vize({
      // options
    }),
  ],
});

TypeScript

Add @vizejs/vite-plugin to compilerOptions.types so TypeScript can resolve direct .vue imports without a project-local env.d.ts shim:

{
  "compilerOptions": {
    "types": ["vite/client", "@vizejs/vite-plugin"]
  }
}

This does not require adding vize as a direct project dependency.

For Vite Plus projects, keep vite-plus/client and append @vizejs/vite-plugin:

{
  "compilerOptions": {
    "types": ["vite-plus/client", "@vizejs/vite-plugin"]
  }
}

Shared config

Put native Vue options in vue: in the existing Vite configuration. The CLI, plugin and editor read the same project settings:

// vite.config.ts
import { defineConfig } from "vite";
import vize from "@vizejs/vite-plugin";

export default defineConfig({
  plugins: [vize()],
  vue: {
    compiler: { sourceMap: true },
    vite: { scanPatterns: ["src/**/*.vue"] },
    linter: { preset: "essential" },
  },
});

Keep TypeScript options in tsconfig.json, including vueCompilerOptions:

{
  "compilerOptions": { "strict": true, "noEmit": true },
  "vueCompilerOptions": { "strictTemplates": true },
  "include": ["src/**/*"]
}

Standard TypeScript extends and references remain supported. The CLI and language server use the selected project's Vite configuration and TypeScript project, including nested packages in a workspace. Explicit plugin options and editor feature switches retain their documented precedence.

Dedicated vize.config.* files and top-level vize: settings are retired. Move native settings to vue: and TypeScript settings to tsconfig.json. A stale dedicated file beside a Vite configuration is ignored; a dedicated-only project receives a migration error. See the configuration guide.

Nuxt

Use the framework module so Nuxt keeps control of its own Vue configuration:

vp install -D @vizejs/nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@vizejs/nuxt"],
});

The module installs the compiler integration and handles the existing Nuxt Vue plugin. See the Nuxt integration guide for module options and project setup.

Options

interface VizeNativeOptions {
  /**
   * Vue major version for the host project.
   * Set to 0.11, 1, 2, or "legacy" to let the existing compiler plugin/loader handle SFCs.
   * @default 3
   */
  vueVersion?: 0.11 | 1 | 2 | 3 | "legacy";

  /**
   * Files to include in compilation
   * @default /\.vue$/
   */
  include?: string | RegExp | (string | RegExp)[];

  /**
   * Files to exclude from compilation
   * @default /node_modules/
   */
  exclude?: string | RegExp | (string | RegExp)[];

  /**
   * Force production mode
   * @default auto-detected from Vite config
   */
  isProduction?: boolean;

  /**
   * Enable SSR mode
   * @default false
   */
  ssr?: boolean;

  /**
   * Enable source map generation. The emitted map's `sources` names the
   * authored `.vue` file, not the virtual `.vue.ts` module.
   * @default true in development, false in production unless `build.sourcemap` is set
   */
  sourceMap?: boolean;

  /**
   * Enable Vapor mode compilation
   * @default false
   */
  vapor?: boolean;

  /**
   * Root directory to scan for .vue files
   * @default Vite's root
   */
  root?: string;

  /**
   * Glob patterns to scan for .vue files during pre-compilation
   * @default ['**\/*.vue']
   */
  scanPatterns?: string[];

  /**
   * Glob patterns to ignore during pre-compilation
   * @default ['node_modules/**', 'dist/**', '.git/**']
   */
  ignorePatterns?: string[];
}

Legacy Vue / Nuxt 2 compatibility

Vize's native SFC compiler targets Vue 3 runtime output. In Vue 0.11, Vue 1, Vue 2, and Nuxt 2 projects, keep the existing host compiler in charge and set:

vize({ vueVersion: 2 });

Use 0.11, 1, 2, or "legacy" for the same host-compiler compatibility mode. This makes the plugin non-invasive: it does not intercept .vue requests, does not expose the Vue 3 vite:vue compatibility API, and does not inject Vue 3 bundler feature flags.

How It Works

Pre-compilation at Startup

When the Vite dev server starts (or build begins), the plugin:

1. Scans the project root for all .vue files matching the configured patterns
2. Compiles each file using the native Vize compiler
3. Stores the compiled JavaScript and CSS in an in-memory cache

This approach leverages Vize's exceptional performance - compiling 15,000 SFC files in under 500ms with multi-threading.

Virtual Module Resolution

When Vite requests a .vue file:

1. The plugin intercepts the module resolution
2. Returns the pre-compiled code from cache (or compiles on-demand if not cached)
3. CSS is injected inline with deduplication support

HMR (Hot Module Replacement)

When a .vue file changes:

1. The plugin detects the change via handleHotUpdate
2. Re-compiles only the changed file
3. Updates the cache
4. Vite handles the rest of the HMR flow

Performance

Vize's native compiler is significantly faster than the official Vue compiler:

Comparison with vite-plugin-vize

Use vite-plugin-vize (WASM-based) when you need:

• Browser compatibility (e.g., StackBlitz, WebContainers)
• Platform-independent deployment

Use vite-plugin-vize when you need:

• Maximum performance
• Server-side only (standard Node.js environment)

Requirements

• Node.js 18+
• Vite 5.0+ / 6.0+ / 7.0+
• Vue 3.x

License

MIT

Framework integrations can pass an inherited whitespace default as the second argument to vize(options, { whitespace: "preserve" }). Project compiler settings and matching entries[].compiler override that default; explicit plugin and nested template compiler options retain their existing precedence.