Vite プラグイン

Warning

Vize は開発を続けており、本番環境への導入準備はまだ整っていません。重要なプロジェクトで採用する前に、十分に検証してください。

バンドラー統合の状況: 現在、最も安定している統合は @vizejs/vite-plugin です。 rollup / webpack / esbuild には @vizejs/unplugin、Rspack には @vizejs/rspack-plugin を使います。 Vite 以外の統合はまだ不安定なため、実験的な機能として扱ってください。

@vizejs/vite-plugin は、Vite プロジェクトの Vue SFC をネイティブコードの速度でコンパイルします。 Vue 3 SFC では @vitejs/plugin-vue を置き換える設計になっており、既存の <script setup> と Options API のコンポーネントをそのまま使えます。

Vite+ から始める

コンパイル、ネイティブの Vue 型チェック、lint、フォーマットをまとめて使う場合は、 Vite+ 用の設定ヘルパー で vite.config.ts に設定します。

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

export default defineConfig({});

移行ガイドに、置き換える import とプラグインの呼び出しを具体的に示しています。 以下の通常の Vite 向け手順では、コンパイラだけを置き換えます。

置き換えの対応範囲

既存プラグインを置き換えられる範囲には、次の制限があります。

• 対応範囲: Vite でコンパイルする Vue 3 SFC が対象です。<script setup> と Options API の両方に加え、scoped style、CSS Modules、SSR、HMR に対応します。
• 開発中: Vue 2 と 2.7（vue.version: "2" / "2.7"、または vize({ vueVersion: 2 })）の互換モードは既定で無効です。このモードでは Vize は .vue ファイルをコンパイルせず、既存の Vue コンパイラ、vue-loader、Nuxt 2 が引き続き処理を担当します。コンパイラ オプションを参照してください。
• 保証の対象外: webpack、rollup、esbuild、Rspack 向けの @vizejs/unplugin と @vizejs/rspack-plugin は実験段階であり、既存プラグインをそのまま置き換えられる保証はありません。実験的なバンドラー統合を参照してください。
• 未完成: @vitejs/plugin-vue の全オプションとの互換性はまだありません。現在は include、exclude、isProduction を反映します。その他の公開オプション、挙動が異なる理由、残る課題は #3227 で追跡しています。

インストール

Vite+ のインストールガイドに従って vp を一度インストールし、パッケージを追加します。

vp install -D @vizejs/vite-plugin

"vize" から共有設定の helper を import する場合や、vize:lint、vize:check などのパッケージスクリプトを用意する場合は、vize も直接の依存関係に追加します。

基本的な使い方

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

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

@vitejs/plugin-vue を @vizejs/vite-plugin に置き換えると、Rust でコンパイルします。 Vite+ の型チェック、lint、フォーマット、ビルドをまとめる場合は、Vite+ の defineConfig() を使ってください。

TypeScript から Vue ファイルをインポートする

compilerOptions.types にプラグインのパッケージを追加すると、ローカルの env.d.ts に型宣言を手書きせずに、TypeScript から .vue ファイルを直接 import できます。

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

この設定のために、vize をプロジェクトの直接の依存関係に追加する必要はありません。

Vite+ のプロジェクトでは、既存の Vite+ のクライアント型を残してプラグインのパッケージを追加します。

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

ネイティブ設定を共有する

Vite+ では @vizejs/vite-plugin/vite-plus の defineConfig(vpConfig).withVue(vueConfig) で、既存の設定にネイティブ Vue 設定を追加します。 通常の Vite では、同じ設定ファイルのトップレベルの vue: に共有設定を置き、 plugins: [vize()] を使います。CLI とエディターも同じプロジェクト設定を読みます。

TypeScript の compilerOptions、標準の extends・references は tsconfig.json に、 Vue テンプレートの設定は vueCompilerOptions に置いてください。 専用の vize.config.* とトップレベルの vize: は廃止しました。 設定ガイドに移行方法を、 共有 Vue 設定にスコープの扱いをまとめています。

コンパイラ オプション

vize() に直接渡したオプションが優先され、次にインラインの config、検索で見つかったプロジェクト設定、既定値の順に適用します。 専用の vize.config.* は廃止しました。vite.config.* の vue: に移してください。 config: false で設定ファイルの自動検索を無効にできます。

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

experimentals の全フラグ、有効にする値、別名、共有設定の優先順位は、Experimentalsを参照してください。

よく使う設定例:

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

// TresJS PascalCase レンダラータグ
vize({
  customRenderer: true,
  customElements: ["Tres*", "primitive"],
});

// Existing templates that rely on parser edge cases, such as
// v-for alias edge parens or `<div />` as a self-closing leaf
vize({ templateSyntax: "quirks" });

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

// Legacy Vue / Nuxt 2 Bridge project with an existing host compiler plugin
vize({ vueVersion: 2 });

vueVersion: 0.11、1、2、"legacy" は、既存のコンパイラとの互換モードです。 これらのモードでは、Vize は .vue ファイルをコンパイルせず、Vue 3 の vite:vue API シムも公開せず、Vue 3 向けのバンドラー機能フラグも挿入しません。 既存の Vue コンパイラプラグイン、vue-loader、Nuxt 2 のコンパイラは、通常どおり設定を残してください。

仕組み

プラグインは .vue ファイルへのリクエストを受け取り、Node.js の NAPI バインディングを介して Vize の Rust パイプラインでコンパイルします。

1. プリコンパイル: buildStart で .vue ファイルを検索し、compileBatch でまとめてコンパイルします。Rust 側では Rayon による並列処理が動き、複数の CPU コアでファイルを処理します。
2. 必要に応じたコンパイル: 開発中にキャッシュにない .vue ファイルが要求された場合（動的 import など）は、compileFile でその場でコンパイルします。
3. HMR: .vue ファイルの変更時は、そのファイルだけを再コンパイルします。変更が style のみに収まるかを判定し、可能な場合は style だけを更新して、コンポーネント全体の再描画を避けます。
4. CSS の抽出: 本番ビルドでは、Vue コンポーネントの scoped CSS を抽出して assets/vize-components.css にまとめ、コンポーネントごとにスタイルを挿入する負荷を減らします。

コンパイルのパイプライン

.vue file
  → Parser            — Tokenizes and parses the SFC structure
  → Semantic analysis — Resolves template expressions and bindings
  → Code generation   — Emits optimized JavaScript (VDOM, SSR, or Vapor)
  → Node.js binding   — Hands the result to Vite
  → Vite module graph — Served as a virtual module

同じ意味解析の仕組みを、lint と型チェックでも使います。 診断を出す処理については、静的解析を参照してください。

比較

高度な機能

バッチプリコンパイル

@vitejs/plugin-vue は、各 .vue ファイルを最初のリクエスト時にコンパイルします。 Vize は、ビルド開始時に見つかったすべての .vue ファイルを、複数スレッドでまとめてプリコンパイルします。

• 開発サーバーの起動: 最初のページを読み込む前に、すべてのコンポーネントを用意します。
• 本番ビルド: 開始時から並列処理を使います。

静的アセットの書き換え

プラグインは、テンプレート内の静的アセット URL を自動で書き換えます。

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

src 属性を import 文に変換し、Vite がハッシュの付与や最適化など、通常のアセット処理を行えるようにします。

define による置き換え

Vite は通常、\0 で始まる仮想モジュールで import.meta.* の置き換えを行いません。 Vize のプラグインは define の置き換えを明示的に適用し、コンパイルした Vue コンポーネントでも import.meta.env.* の値を正しく使えるようにします。

環境ごとの分離

Nuxt と連携できるよう、プラグインは Vite の環境ごとに define の値を分けます。 クライアントとサーバー/SSR を分離し、クライアント用の値が SSR の出力に入り込むのを防ぎます。

スタイルプリプロセッサと Pug

<style lang="scss">・sass・less・stylus は Vue と同じ順序で処理します。まずプリプロセッサを実行し、その出力に Vize がスコープを付けて v-bind() を解決します。<style module> のクラス名は、バンドラーの CSS Modules 処理が生成します。@vitejs/plugin-vue と同じく、プリプロセッサのパッケージ（sass または sass-embedded、less、stylus）をプロジェクトにインストールしてください。<template lang="pug"> は Vize 自身がコンパイルするため、追加のパッケージは不要です。従来の <template lang="jade"> も同じ対象でエイリアスとして利用できます。

Nuxt との連携

プラグインは、Nuxt などが @vitejs/plugin-vue の API を確認する際に使える互換性シムを公開しています。 この仕組みにより、Nuxt に組み込まれた Vue の処理とも連携できます。

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

詳しくは、Nuxt との連携ガイドを参照してください。

注意事項

• Node.js の NAPI バインディングには @vizejs/native が必要です。依存関係として自動でインストールされます。
• Vapor モードのコンパイルに対応しています（Vue 3.6 以降、実験段階）。
• コンパイルしたすべての CSS をモジュールとして import するために、virtual:vize-styles を使えます。
• .jsx / .tsx の Vue コンポーネントも同じプラグインで自動でコンパイルします。JSX と TSXを参照してください。
• rollup / webpack / esbuild / Rspack への実験的な対応は、実験的なバンドラー統合を参照してください。