ソース配布 (`vize lib`)

vize lib は @vizejs/ui のコンポーネントと @vizejs/composable のコンポーザブルを、shadcn/ui と同じスタイルで ソースとして プロジェクトにコピーします。コピーしたファイルはあなたのものです。自由に編集でき、 Vize は各ファイルがどのパッケージバージョン由来かを記録するので、アップグレードも安全に行えます。

コンポーネントをアプリ内で直接変更したいときに、ソース配布を使ってください。パッケージの import で十分な場合は UI ライブラリやコンポーザブルから始められます。まず下の rating の例でコピーを試し、変更後はこのページの更新手順で差分を確認してください。

vpx vize lib pull rating

rating ファミリーと、それが import するもの (controllable-state、id など) がすべて src/components/vize/ に書き込まれ、vize-lib.lock.json に記録されます。

取得したコンポーネントを表示する

この例は Vue 3.5 以降を使う Vue 3 アプリで、既定の src/components/vize にソースを置く手順です。まず、取得元のバージョンと必要な npm パッケージを確認し、同梱された使用例も取得します。

vpx vize lib info rating
vpx vize lib pull rating --with-examples --dry-run
vpx vize lib pull rating --with-examples

最後のコマンドを実行する前に、dry-run のファイル一覧を確認してください。pull は宣言されていないパッケージを報告しますが、依存のインストールやバージョンの互換性の確認は行いません。アプリを起動する前に、必要なパッケージをパッケージマネージャーで追加してください。取得したソースは .ts ファイルを直接 import するため、アプリの TypeScript 設定で allowImportingTsExtensions を有効にします。init の手順で、この設定を確認する方法を説明しています。

使用例は src/components/vize/families/form/rating/examples/rating-basic.vue に保存されます。新しいアプリでは、src/App.vue から次のように表示できます。

<script setup lang="ts">
import RatingExample from "./components/vize/families/form/rating/examples/rating-basic.vue";
</script>

<template>
  <RatingExample />
</template>

初期値は星 3 個です。別の星を選ぶと値と表示が変わり、選択中の星をもう一度選ぶと値が空になって Not rated と表示されます。操作には標準のラジオボタンを使い、ラベルも関連付けています。コンポーネント自体に見た目のスタイルは付いていないため、アプリ側の CSS で調整してください。

使用例は隣にある取得済みの rating.ts を import するので、コンポーネントを編集するとアプリにも反映されます。配置先ディレクトリを変更した場合は、App.vue の import も合わせて変更してください。vize-lib.lock.json をバージョン管理に含め、取得したファイルの変更後はこのページの更新手順で差分を確認できます。

ソースの取得元

公開されている @vizejs/ui と @vizejs/composable の tarball には、バージョン付きのレジストリが含まれています。

node_modules/@vizejs/ui/
  registry/
    registry.json          # アイテム、ファイル、sha256 ダイジェスト、依存関係
    files/families/...     # 生の .vue / .ts / .css ソース (テストは除外)

vize lib は次の順序でレジストリを解決します。

--registry <path>: registry.json、そのディレクトリ、または展開済みパッケージのディレクトリ。ui と composable の両方を渡すにはフラグを繰り返します。この場合、自動検出は無効になります。
プロジェクトにインストール済みのパッケージ (node_modules/@vizejs/ui/registry/registry.json。Node の解決と同様に親ディレクトリも探索します)。
インストール済みのバージョンと一致しないバージョンが指定された場合、またはパッケージが未インストールの場合 (@latest) は、npm pack @vizejs/<pkg>@<version> を一時ディレクトリに実行し tar -xzf で展開します。 --offline を指定するとこの手順を禁止します。

レジストリサーバーや追加の HTTP クライアントは使いません。レジストリは npm がすでに配信している tarball そのものなので、すべてのバージョンは不変で再現可能です。

コマンド

コマンド	内容
`vize lib init [--dry-run]`	プロジェクト構成を検出して `lib` 設定セクションを書き込みます。
`vize lib list [--kind ui\|composable]`	取得可能なアイテムを一覧表示します。
`vize lib search <words>`	名前、タイトル、説明、エイリアスで検索します。
`vize lib info <name>`	ファイル、レジストリ依存、npm peer、パッケージバージョンを表示します。
`vize lib pull <item>... [--dir <dir>]`	アイテムとレジストリ依存をコピーします。`--dry-run`、`--overwrite`、`--with-examples`。
`vize lib add <item>...`	shadcn 互換の `pull` のエイリアス (`-p/--path`、`-o/--overwrite`、`-y/--yes`)。
`vize lib status`	取得済みファイルをロックファイルとインストール済みレジストリと比較します。
`vize lib diff <name> [--to <version>]`	ローカルのコピーからレジストリのバージョンへの unified diff を表示します。
`vize lib update [<name>...] [--to <v>]`	ローカルの編集を壊さずに upstream の変更を適用します。`--dry-run`、`--force`。
`vize lib remove <name>...`	アイテムと、他に必要とされない依存を削除します。`--dry-run`、`--force`。
`vize lib outdated`	ロックされたバージョンをインストール済み・最新のレジストリと比較します。

すべてのコマンドは機械可読な出力のための --json と、別のプロジェクトを対象にする --root <dir> を受け付けます。

アイテムの指定

アイテムは正規名 (rating)、エイリアス (star rating、useToggle)、両方のパッケージに同名がある場合の種類プレフィックス (ui:locale、composable:locale)、正確なパッケージバージョン ([email protected]、 composable:[email protected]) で指定できます。

配置先ディレクトリ

取得したファイルは種類ごとに 1 つのディレクトリの下でレジストリのレイアウト (families/form/rating/rating.vue、foundations/id/deterministic-id.ts など) を保つため、アイテム間の相対 import は書き換えなしでそのまま動作します。ディレクトリは次の順で決まります。

--dir <dir> (プロジェクト内である必要があります)
既存の Vite 設定にある共通の vize.lib 設定
レジストリの既定値: src/components/vize (ui)、src/composables/vize (composable)

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

export default defineConfig({
  vize: {
    lib: {
      uiDir: "src/ui/vendor",
      composableDir: "src/composables/vendor",
      // dir: "src/vendor",
      // lockfile: "vize-lib.lock.json",
    },
  },
});

既存の専用設定の lib も利用できます。優先順位と公開済みバージョンの対応範囲は設定ガイドを参照してください。

ある種類を一度ディレクトリに取得すると、その種類の以降の取得は同じディレクトリを使います。依存グラフを分割してしまう競合する --dir は拒否されます。

取得したソースが import するのは相対パスと vue などの npm パッケージだけです。pull は package.json にまだ宣言されていない npm 依存を報告しますが、パッケージのインストールは行いません。

はじめに: `init`

vize lib init --dry-run   # 検出した構成と設定の変更を表示
vize lib init             # 書き込む

init はソースディレクトリ（通常は src/、Nuxt 4 では app/）と TypeScript を検出します。設定がなければ、新しい vite.config.mjs に vize.lib.uiDir と vize.lib.composableDir を書き込みます。既存の Vite 設定は編集せず、設定を追加する必要があれば vize.lib のスニペットを表示します。

既存の専用設定では従来の動作を維持します。vize.config.json には lib を追加し、コードや Pkl の設定ではスニペットを表示します。既存の lib は保持し、専用 JSON の場合は --force で置き換えられます。tsconfig.json に allowImportingTsExtensions がなければ、その旨を表示します。取得したソースは兄弟ファイルを ./x.ts として import します。

更新の確認: `outdated`

vize lib outdated はレジストリがロックファイルと異なる取得済みアイテムを一覧表示します。

列	意味
`current`	`vize-lib.lock.json` に記録されたバージョン。
`wanted`	`update` が使うレジストリのバージョン (インストール済みパッケージ、なければ最新)。
`latest`	npm で公開されている最新バージョン (`npm view`。`--offline` では省略)。
`state`	`update-available`、`newer-release`、`removed-upstream`、`unknown` (または `up-to-date`)。

update-available はアイテムの contentHash が異なることを意味します。アイテムのファイルに触れないバージョンアップでは up-to-date のままです。--json はすべてのアイテムを含みます。

サードパーティのレジストリ

どのパッケージやサイトでも同じ形式のレジストリを公開し、名前空間の下で使えるようにできます。

{
  "lib": {
    "registries": {
      "@acme": "npm:@acme/vue-kit",
      "@design": { "source": "https://design.example.com/r/registry.json", "dir": "src/design" },
      "@local": { "source": "./registry", "dir": "src/local" }
    }
  }
}

vize lib pull @acme/data-table @design/[email protected]
vize lib list --kind @acme

npm:<package>[@range] はインストール済みパッケージの registry/registry.json を使い、なければ npm pack します。
https://…/registry.json は curl で取得し、各ファイルは隣の files/<path> から必要に応じてダウンロードします (https のみ)。
それ以外は設定ファイルからの相対パスです: registry.json、そのディレクトリ、またはパッケージディレクトリ。

サードパーティのレジストリはファーストパーティと同じ JSON Schema で検証され (未知のフィールド、不正なダイジェスト、未知のロールや依存、不完全な依存閉包は拒否)、ダウンロードしたすべてのバイトは書き込み前に SHA-256 で検証されます。名前空間のアイテムはその dir (なければレジストリの defaultTargetDirectory) に置かれ、@namespace キーでロックされ、他の取得済みアイテムが所有するファイルを上書きすることはありません。

使用例と Musea ギャラリー

多くの UI ファミリーは、ソースの隣にスタイルなしの使用例を同梱しています (families/<area>/<family>/examples/<family>-*.vue)。レジストリに含まれますが、要求したときだけ取得されます。

vize lib pull switch --with-examples

使用例は取得したソースの隣 (…/switch/examples/switch-basic.vue) に置かれ、相対パスでファミリーを import し、他のファイルと同じく vize-lib.lock.json で追跡されるため、status、diff、update の対象になります。一度要求すると update でも取得され続けます。

同じ使用例から、ファミリーごとに 1 つのストーリー、使用例ごとに 1 つのバリアントを持つ Musea ギャラリーが生成されます。チェックアウトでは examples/vite-musea で pnpm gallery:ui を実行すると、ストーリーを再生成 (npm/ui/scripts/generate-gallery.ts) してギャラリーを起動します。

バージョン管理と安全な更新

vize-lib.lock.json (コミットしてください) には、アイテムごとに取得元のパッケージと正確なバージョン、レジストリの contentHash、直接要求したか依存として入ったか、そして取得時の各ファイルの SHA-256 が記録されます。これらのダイジェストが あなたのファイル、取得時のファイル、新しいレジストリのファイル の 3-way 比較のマージベースになります。

あなたのファイル vs 取得時	レジストリ vs 取得時	`update` / `pull` の動作
変更なし	変更なし	何もしない (`unchanged`)
変更なし	変更あり	置き換える (`update`)
編集あり	変更なし	編集を保持する (`keep-local`)
編集あり	変更あり	`--force` / `--overwrite` がなければ拒否 (`conflict`)
変更なし	upstream で削除	削除する (`delete`)
編集あり	upstream で削除	`--force` がなければ拒否 (`conflict-delete`)
存在しない	任意	復元する (`create`)
存在するがロック外	任意	`--overwrite` がなければ拒否 (`conflict`)

未解決の競合がある間は何も書き込まれないため、拒否された更新はファイルもロックファイルも変更しません。 vize lib diff <name> --to <version> で upstream の変更を確認し、手でマージしてから update --force を実行してください。

典型的なアップグレード:

pnpm add @vizejs/ui@latest       # または: vize lib update --to 0.428.0
vize lib status                  # 更新やローカル編集のあるアイテム
vize lib update --dry-run        # ファイル操作をプレビュー
vize lib update                  # 適用。競合があれば一覧表示

remove はアイテムと、そのためだけに取得された依存をすべて削除します。他の取得済みアイテムがまだ対象を import している間は拒否し、--force がない限りローカルで編集されたファイルは残します。

レジストリの形式

レジストリドキュメントは vize-lib-registry.schema.json、ロックファイルは vize-lib-lock.schema.json で定義されています。どちらも vize npm パッケージの schemas/ に同梱されています。

registryDependencies はビルド時に相対 import グラフから計算した完全な推移閉包です。共有の基盤は別アイテムなので、どちらも id を必要とする 2 つのコンポーネントを取得しても id は一度だけコピーされます。
各ファイルは sha256 を持ち、vize lib はコピーするすべてのバイトをそれで検証します。
contentHash はアイテムのファイルが変わったときだけ変化するため、status はバージョン間で実際にソースが異なるアイテムについてのみ「update available」を報告します。

ソース配布 (vize lib)