インストール

pnpm、npm、yarn、bun の各プロジェクトへ @takazudo/zdtp をインストールします。

@takazudo/zdtp は通常の npm パッケージです。Astro、Vite + React、Next.js、プレーンな Vite、ZFB 3/4 などのブラウザーホストで動作します。configurePanel({...}) が独立した Preact のシェルをマウントし、ホストは自身のレンダラーを使い続けます。

このページではパッケージ自体のインストールを説明します。レイアウトへの組み込みについてはクイックスタートを参照してください。

パッケージをインストールする

プロジェクトのパッケージマネージャーに合うコマンドを選んでください。ZDTP は Preact を通常の依存関係として持ちます。命令型 API を使うホストではパネルだけを指定し、ホストの JSX ランタイムは React や zudo-react のまま使えます。

pnpm

pnpm add @takazudo/zdtp

npm

npm install @takazudo/zdtp

yarn

yarn add @takazudo/zdtp

bun

bun add @takazudo/zdtp

ZDTP 自身が Preact を持ちます

0.8.6 から Preact ^10.29.1 は peer ではなく通常の依存関係です。公開宣言には引き続き Preact の型が含まれ、その依存関係から解決されます。独自の Preact JSX や @takazudo/zdtp/dashboard を描画するホストは、自身の Preact と SSR 用依存関係を宣言してください。非公開ランタイムをバンドルする方式ではありません。パネルのツリーは他のレンダラーと分離します。

インストールを確認する

インストール後、パッケージはプロジェクトルートから確認できる次の 3 種類を公開します。

ライブラリエントリ — @takazudo/zdtp（configurePanel を呼び出し、パネルをレンダリングします）。
Astro エントリ — @takazudo/zdtp/astro/DesignTokenPanelHost.astro（Astro がコンパイルできるよう直接 import する <DesignTokenPanelHost> コンポーネント）と @takazudo/zdtp/astro（設定型とヘルパー）。ホストアダプターは副作用 import の @takazudo/zdtp/astro/host-adapter です。
CLI bin — apply パイプラインで使う zdtp-server。

プロジェクト内の PATH から bin を実行できるか、次のコマンドで確認できます。

pnpm exec zdtp-server --help
# or
npx zdtp-server --help

ヘルプが表示されれば、パッケージは正しくインストールされています。

apply パイプライン用 bin

パッケージには zdtp-server という実行ファイルが含まれます。開発サーバーと並行して動作し、ループバックポートで待ち受け、パネルで Apply をクリックしたときにトークン CSS ファイルを書き換えます。

今は省略できます

bin は任意です。bin がなくても、エクスポート／インポートモードでパネルの全機能を利用できます。パネル上の変更をディスクへ反映したくなった時点で組み込んでください。

完全な CLI リファレンスは専用ページにあります。概要は次のとおりです。

npx zdtp-server \
  --routing ./panel-routing.json \
  --write-root ./tokens \
  --allow-origin http://localhost:5173

ランタイム依存関係の境界

ZDTP は Preact、@tailwindcss/browser、tailwind-merge、culori を通常の依存関係としてインストールします。Tailwind コンパイラーは DOM Tweaker の遅延有効化境界の内側にあり、通常のパネルを開いても読み込み・実行されません。Tailwind を一切インストールしない構成ではありません。別パッケージや任意のエントリへの分離は、互換性を別途検討する変更です。optionalDependencies に移しても既定ではインストールされます。

ZFB 3/4 では getScope().onActivate() 内でパネルを import し、アイランドの破棄時に読み込み待ちをキャンセルします。そのライフサイクル内で返されたハンドルを設定・破棄してください。Preact の VNode をホストの zudo-react レンダラーに渡してはいけません。

Info

パネルの CSS は自己完結しています。パネル専用の --tokentweak-* 名前空間にまとめたスタイルシートが同梱されています。パネルを利用するプロジェクトに Tailwind は不要です。

スタイルの import は不要です

パネルは実行時に自身のスタイルシートを注入します。初めてパネルを開くと、バンドル済み CSS を持つ <style> 要素を追加します。CSS を利用側で import する必要はありません。@takazudo/zdtp/styles（および /styles.css）の export も引き続きバンドル済みスタイルシートへ解決されるため、独自のスタイルシートパイプラインへ取り込みたい場合は利用できますが、現在は任意です。

次のステップ

インストールは完了です。最小限の一連の組み込みはクイックスタート、Astro / Vite + React / Next.js の比較はフレームワーク比較へ進んでください。