vize init で既存プロジェクトに導入する

vize init は、既存のプロジェクトに Vize を導入するためのコマンドです。 検出結果を確認し、必要な機能を選ぶと、設定ファイルの編集と依存パッケージのインストールを進めます。 通常は対話形式で実行し、フラグで選択肢を指定することもできます。 プロジェクトの package.json があるディレクトリから実行してください。

vpx vize init

選べる機能は次の5つです。ビルド連携には、Vite と Nuxt の2通りがあります。

Vite プラグインと Nuxt モジュールは、どちらも「ビルド連携」の選択肢です。 init がプロジェクトを検出し、使用する連携方法を選びます。

init は既存の設定を保ちながら編集し、専用の Vize 設定ファイルは新規作成しません。 共通設定と、使用しているリリースでの対応状況は設定ガイドで確認してください。

最初に確認する検出結果

機能を選ぶ前に、プロジェクトの検出結果が表示されます。 対象のディレクトリやパッケージマネージャーが正しいか、ファイルを変更する前に確認してください。

[vize init] detected in /path/to/project:
  framework:       Vite+ (vite.config.ts)
  package manager: pnpm
  language:        TypeScript (tsconfig.json)
  lint command:    vp lint
  Vue settings:    vue: in vite.config.*
  oxlint config:   none

lint コマンドが読むファイルに設定する

設定ファイルを作っても、実行するコマンドがそのファイルを読み込まなければ lint は有効になりません。

Vite+ は .oxlintrc.json を読み込みません。.oxlintrc.json に jsPlugins と vize/* のルールを 書いても、vp lint では使われず、Oxlint に vize/* のルールが渡りません。 そのため、Vize の診断が0件でも終了コードは 0 になり、設定できたように見えてしまいます。 詳しくは Oxlint プラグインの設定を参照してください。

init は、プロジェクトで実行する lint コマンドに合わせて設定先を選びます。

lint ブロックは createVizeLintConfig() で作成します。 プラグインの読み込みに必要な jsPlugins を含む設定一式が返るため、その項目を追加し忘れることを防げます。 次の例は lint の設定部分を示しています。既存のプラグインの import などは、プロジェクトの構成に合わせてください。

// vite.config.ts
import { defineConfig } from "vite-plus";
import { createVizeLintConfig } from "oxlint-plugin-vize";

export default defineConfig({
  lint: createVizeLintConfig({
    preset: "happy-path",
    settings: {
      helpLevel: "short",
    },
  }),
  plugins: [vize()],
});

Vite+ を使わない場合は、同じ内容を oxlint.config.ts に設定します。

import { defineConfig } from "oxlint";
import { configs } from "oxlint-plugin-vize";

export default defineConfig({
  plugins: ["vue"],
  jsPlugins: ["oxlint-plugin-vize"],
  settings: {
    vize: {
      preset: "happy-path",
      helpLevel: "short",
    },
  },
  rules: configs.happyPath,
});

Note

Oxlint が自動で読み込むのは .oxlintrc.json、.oxlintrc.jsonc、oxlint.config.ts です。 oxlint.config.mjs、.js、.cjs、.mts、.cts は自動検出されません。 これらのファイルがあっても、init は「存在するが読み込まれない」と表示し、有効な設定とは扱いません。

CI など対話できない環境で実行する

標準入力が TTY でない場合、init は入力を待たずに終了します。 CI などでは --yes と機能を選ぶフラグを指定してください。

vpx vize init --yes --lint --vite --fmt --typecheck --editor

この例は --vite で Vite プラグインを明示的に選んでいます。Nuxt のプロジェクトでは、 代わりに Nuxt モジュールの選択肢を使ってください。機能のフラグは検出結果を上書きします。 指定していない機能は検出時の選択を引き継ぐため、不要な機能は次の表の無効化用フラグで除外します。

--dry-run は機能を選んだ後、変更予定を表示して終了します。ファイルの書き込みや 依存パッケージのインストールは行いませんが、自動承認を指定しなければ通常どおり対話が必要です。 対話できない環境で変更予定だけを確認するには、vpx vize init --yes --dry-run を実行してください。 次は、既存の TypeScript 設定がある Vite+ プロジェクトでの表示例です。

[vize init] plan:
  lint      configured Vite+ detected, so `vp lint` reads the `lint` block in vite.config.ts and never reads .oxlintrc.json; writes vite.config.ts
  bundler   configured adds vize() to vite.config.ts
  fmt       configured uses project settings and formatter defaults
  typecheck configured uses tsconfig.json and project settings
  editor    configured writes .vscode/extensions.json recommending ubugeeei.vize
[vize init] would create .vscode/extensions.json
[vize init] would update vite.config.ts
[vize init] would update package.json
[vize init] would add scripts: vize:lint, vize:fmt, vize:fmt:fix, vize:check
[vize init] would run: vp add -D @vizejs/vite-plugin oxlint oxlint-plugin-vize vize

設定後にもう一度実行する

init で設定と依存パッケージの導入が正常に完了した後は、同じ機能とインストール設定で再実行しても、 プラグイン、スクリプト、依存パッケージが重複して追加されることはありません。変更が不要なファイルは、そのまま保たれます。

[vize init] plan:
  lint      unchanged  Vite+ detected, so `vp lint` reads the `lint` block in vite.config.ts and never reads .oxlintrc.json
  bundler   unchanged  vite.config.ts already uses @vizejs/vite-plugin
  fmt       unchanged  uses project settings and formatter defaults
  typecheck unchanged  uses tsconfig.json and project settings
  editor    unchanged  .vscode/extensions.json already recommends ubugeeei.vize
[vize init] nothing to do; the project is already configured

設定済みの機能は、選択画面でも選択済みの状態で表示されます。 後から機能を追加する場合も、すべてを選び直す必要はありません。

自動編集できない場合と途中で失敗した場合

init は、安全に変更できない設定を推測で書き換えません。その設定の編集をユーザーに委ね、 対象の機能を未設定と表示して、追加するコード例を案内します。他の設定変更やスクリプトの追加、 依存パッケージのインストールは進む場合があります。編集できない機能があると終了コードは0以外になるため、 表示された計画と実際のファイルの差分を確認してください。

ファイルの書き込みと依存パッケージのインストールは別々に進みます。途中でエラーが起きると、 それまでの変更が残る場合があります。表示されたエラーを解消し、変更内容を確認してから再実行してください。

Vite+ に Vize の lint 機能を新しく導入する場合は、既存の lint ブロックに注意してください。 Vize の連携がまだ検出されていなければ、init は既存の設定を失わないよう、 自動でまとめて書き換えることを避けます。Vize の連携がすでに検出されている場合は、その設定を保持します。 次は、新規導入時に自動編集できない場合の表示例です。

[vize init] lint: NOT configured — vp lint reads the `lint` block in the Vite config, but
vite.config.ts already has a `lint` block and merging into it would risk dropping settings, so
spread createVizeLintConfig() into it by hand

    import { createVizeLintConfig } from "oxlint-plugin-vize";

    export default defineConfig({
      lint: {
        ...createVizeLintConfig({
          preset: "happy-path",
          settings: {
            helpLevel: "short",
          },
        }),
        // keep your existing lint keys here
      },
    });

この場合、代わりに別の oxlint.config.ts を作ることはありません。それを作っても vp lint は 元の lint ブロックを読み続けるため、必要な診断が出ないままになってしまうからです。 表示されたコード例を、既存の設定を保ちながら手動で組み込んでください。

その他の設定ファイルの編集にも制限があります。Vite 設定が複数ある場合、init は lint の設定先を 決められません。単一の defineConfig({ ... }) 呼び出しではない設定や、配列リテラルではない plugins は、安全に編集できないことがあります。.vscode/extensions.json の JSON の形式が 対応していない場合も同様です。実行全体で何も変更されなかったとは限らないため、機能ごとの結果を確認してください。

チーム向けのエディター設定

init は、プロジェクトで推奨する拡張機能を設定ファイルに記録します。

{
  "recommendations": ["ubugeeei.vize"]
}

このファイルをコミットすると、チーム全員が同じ推奨設定を使えます。init を実行した端末に 拡張機能が自動でインストールされるわけではありません。init の結果には、VS Code 以外の連携方法も表示されます。

各エディターへの導入手順は VS Code とその他のエディターを参照してください。

vize setup との使い分け

vize setup は、Vite または Vite+ のプロジェクトをまとめて設定する従来のコマンドです。 init では機能を選べるほか、Nuxt、パッケージマネージャーの検出、変更予定の確認、 対話なしでの実行にも対応しています。既存プロジェクトへ導入する機能を選びたい場合は、vize init を使ってください。

導入後に確認すること

• 静的解析の使い方で、lint と型チェックの役割を確認します。
• Oxlint プラグインの設定で、プリセットや設定項目を確認します。
• 共通設定の使い方で、プロジェクトの設定を調整します。
• CLI のコマンド一覧で、他の操作を確認します。