Vite Plugin

⚠️ Work in Progress: Vize is under active development and is not yet ready for production use. Test thoroughly before adopting in non-trivial projects.

Bundler status: @vizejs/vite-plugin is currently the most stable bundler integration. For rollup / webpack / esbuild use @vizejs/unplugin, and for Rspack use @vizejs/rspack-plugin. Those non-Vite paths are still unstable and should be treated as experimental.

@vizejs/vite-plugin provides native-speed Vue SFC compilation for Vite projects. It is designed as a drop-in replacement for @vitejs/plugin-vue — your existing Vue components work without modification.

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" or runs the npm CLI through vp exec vize.

Basic Usage

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

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

That's it. Replace @vitejs/plugin-vue with @vizejs/vite-plugin and your project compiles through Rust.

TypeScript Vue Imports

Add the plugin package to compilerOptions.types to make direct .vue imports resolvable by TypeScript without writing a 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 the Vite Plus client type and append the plugin package:

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

For most projects, keep direct plugin options small and put stable compiler settings in vize.config.ts.

Shared Config

The recommended shared entry point is vize. A single vize.config.* file is read by both the npm CLI and @vizejs/vite-plugin.

vp install -D vize

Supported config files:

• vize.config.pkl

• vize.config.ts

• vize.config.js

• vize.config.mjs

• vize.config.json

TypeScript config:

// vize.config.ts
import { defineConfig } from "vize";

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

PKL config:

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

compiler {
  sourceMap = true
}

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

JSON config with schema:

{
  "$schema": "./node_modules/vize/schemas/vize.config.schema.json",
  "vite": {
    "scanPatterns": ["src/**/*.vue"]
  }
}

Importing defineConfig from @vizejs/vite-plugin still works for backward compatibility, but import { defineConfig } from "vize" is the shared path going forward.

See Configuration for the full shared config shape.

Vite Plus-first projects can also keep startup-only settings inline in vite.config.ts:

import { defineConfig } from "vite-plus";
import vize from "@vizejs/vite-plugin";

export default defineConfig({
  plugins: [
    vize({
      config: {
        compiler: {
          sourceMap: true,
          vapor: false,
        },
        vite: {
          scanPatterns: ["src/**/*.vue"],
        },
        musea: {
          include: ["src/**/*.art.vue"],
        },
      },
    }),
  ],
});

Inline config is available to the Vite plugin and shared plugin store during Vite Plus execution. Use vize.config.* for settings that must also be read by CLI and LSP commands.

Compiler Options

Direct options passed to vize() override vize.config.*. The full precedence is direct plugin options, then inline config, then vize.config.*, then defaults.

vize({
  sourceMap: true,
  ssr: false,
  vapor: false,
  customRenderer: false,
  vueParserQuirks: false,
  scanPatterns: ["src/**/*.vue"],
  ignorePatterns: ["node_modules/**", "dist/**", ".git/**"],
});

Common recipes:

// Vapor-oriented build
vize({ vapor: true });

// TresJS or another custom renderer
vize({ customRenderer: true });

// Existing templates that rely on Vue's v-for alias edge-paren behavior
vize({ vueParserQuirks: true });

// Monorepo package with explicit scan roots
vize({
  root: import.meta.dirname,
  scanPatterns: ["src/**/*.vue", "examples/**/*.vue"],
});

How It Works

The plugin intercepts .vue file requests and compiles them using Vize's Rust-native pipeline through Node.js NAPI bindings:

1. Pre-compilation — At buildStart, the plugin discovers all .vue files and compiles them in batch using compileBatch. This triggers Rayon-based parallel compilation on the Rust side, processing all files across all CPU cores simultaneously.

2. On-demand compilation — During development, if a .vue file is requested that isn't in the cache (e.g., dynamically imported), it's compiled on-the-fly via compileFile.

3. HMR — When a .vue file changes, only that file is recompiled. The plugin detects whether the change is style-only and applies a style-only HMR update when possible, avoiding a full component re-render.

4. CSS extraction — In production builds, all scoped CSS from Vue components is extracted and merged into assets/vize-components.css, eliminating per-component style injection overhead.

Compilation Pipeline

.vue file
  → Armature (Parser)          — Tokenizes and parses the SFC structure
  → Croquis (Semantic Analysis) — Analyzes template expressions and bindings
  → Atelier (Compilation)       — Generates optimized JavaScript output
  → Vitrine (NAPI Binding)      — Delivers the result to Node.js
  → Vite module graph            — Served as a virtual module

The same semantic analysis layer is reused by linting and type checking. See Static Analysis for the diagnostic side of the pipeline.

Comparison

Advanced Features

Batch Pre-compilation

Unlike @vitejs/plugin-vue, which compiles each .vue file on first request, Vize pre-compiles all discovered .vue files at build start using multi-threaded batch compilation. This means:

• Dev server startup — All components are ready before the first page load

• Production builds — Maximum parallelism from the start

Static Asset Rewriting

The plugin automatically rewrites static asset URLs in templates. For example:

<template>
  <img src="./logo.png" />
</template>

The src attribute is hoisted to an import statement, allowing Vite to process the asset through its asset pipeline (hashing, optimization, etc.).

Define Replacement

Vite normally skips import.meta.* replacement for virtual modules (prefixed with \0). Vize's plugin manually applies define replacements to ensure import.meta.env.* values work correctly in compiled Vue components.

Per-Environment Isolation

For Nuxt compatibility, the plugin isolates define values per Vite environment (client vs. server/SSR). This prevents client-side environment values from leaking into SSR output.

Nuxt Compatibility

The plugin exposes a compatibility shim for tools that probe for @vitejs/plugin-vue's API (like Nuxt). This means Vize works with Nuxt's built-in Vue integration without special configuration:

// nuxt.config.ts — using the dedicated Nuxt module
export default defineNuxtConfig({
  modules: ["@vizejs/nuxt"],
  vize: {
    compiler: true,
  },
});

See Nuxt Integration for more details.

Notes

• The plugin requires @vizejs/native for Node.js NAPI bindings (installed automatically as a dependency)

• Vapor mode compilation is available via vize_atelier_vapor (Vue 3.6+)

• DOM (VDom) compilation uses vize_atelier_dom

• The plugin supports virtual:vize-styles for importing all compiled CSS as a module

• For experimental rollup / webpack / esbuild / Rspack support, see Experimental Bundler Integrations