@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";

export default defineConfig({
  compiler: { sourceMap: true },
  typecheck: { strict: true },
  lint: { vize: { preset: "essential", typecheck: true } },
  fmt: { vize: { 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.

Use extends for shared presets and pack.vize for native declarations, declaration maps, and compiler maps. vize.lint.typecheck is also supported. withVue and withVize are aliases with the same single-object API.

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

vize.config.ts

import { defineConfig } from "vize";

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

vize.config.pkl

amends "node_modules/vize/pkl/vize.pkl"

compiler {
  sourceMap = true
}

vite {
  scanPatterns = new Listing {
    "src/**/*.vue"
  }
}

@vizejs/vite-plugin loads the same vize.config.ts, vize.config.js, vize.config.mjs, vize.config.pkl, and vize.config.json files as the vize npm CLI. Importing defineConfig from @vizejs/vite-plugin still works, but vize is the shared entry point. Install @pkl-community/pkl or provide a pkl binary on PATH when using vize.config.pkl.

Nuxt

For Nuxt 3, add the plugin to your nuxt.config.ts:

// nuxt.config.ts
import vize from "@vizejs/vite-plugin";

export default defineNuxtConfig({
  vite: {
    plugins: [
      vize({
        // Exclude Nuxt's internal .vue files if needed
        exclude: [/node_modules/, /#/, /\.nuxt/],
      }),
    ],
  },

  // Disable the default Vue plugin
  vue: {
    propsDestructure: false,
  },
});

Note: When using with Nuxt, you may need to disable Nuxt's built-in Vue plugin to avoid conflicts:

// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    "vite:extendConfig": (config) => {
      // Remove @vitejs/plugin-vue from plugins
      config.plugins = config.plugins?.filter(
        (p) => p && (Array.isArray(p) ? p[0] : p).name !== "vite:vue",
      );
    },
  },
  vite: {
    plugins: [vize()],
  },
});

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:

| Benchmark (15,000 SFCs) | @vue/compiler-sfc | Vize | Speedup | | ----------------------- | ----------------- | ----- | --------- | | Single-threaded | 9.35s | 3.47s | 2.7x | | Multi-threaded | 4.08s | 353ms | 11.6x |

Comparison with vite-plugin-vize

| Feature | vite-plugin-vize | vite-plugin-vize | | --------------- | ---------------- | --------------------- | | Compiler | WASM | Native (NAPI) | | Pre-compilation | No | Yes | | Module Loading | Transform | Virtual Module (Load) | | Performance | Fast | Fastest | | Platform | Any | Node.js only |

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.