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

npm install @vizejs/vite-plugin 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.

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.

Supported config files:

• vize.config.ts

• vize.config.js

• vize.config.mjs

• vize.config.pkl

• vize.config.json

TypeScript config:

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

export default defineConfig({
  compiler: {
    sourceMap: true,
  },
  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.

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

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