Webダッシュボードのビルド

web/ にあるWebダッシュボードは、Vite + React + TypeScriptアプリです。そのTypeScript APIクライアントは手書きではなく、ゲートウェイのランタイムOpenAPI仕様から生成されます。

クイックスタート

sh

cargo web build         # production bundle を web/dist/ へ
cargo web dev           HMR 対応の vite 開発サーバー
cargo web check         # typecheck のみ (gen-api + tsc -b)
cargo web gen-api       # web/src/lib/api-generated.ts を再生成する
cargo web install       # web/ での npm install

cargo web は cargo run -p xtask --bin web -- のエイリアスです（cargo の設定で定義されています）。すべてのサブコマンドは、web/node_modules/ が存在しない場合に自動的に npm install を実行します。

生成される内容

パス	ジェネレーター	追跡対象？
`web/src/lib/api-generated.ts`	`cargo web gen-api`	gitignore対象
`target/openapi.json`	`cargo web gen-api`	gitignore対象
`web/dist/`	`cargo web build`	gitignore対象

cargo web gen-api は zeroclaw_gateway::openapi::build_spec() からプロセス内で OpenAPI 仕様をレンダリングし、それを target/openapi.json に書き出して、そのファイルを openapi-typescript に渡します。同じ build_spec() が実行時に /api/openapi.json を提供するため、build_spec() が唯一の契約ソースとなり、生成されたファイルはオンデマンドで再ビルドされます。

編集フロー

crates/zeroclaw-gateway/ のゲートウェイハンドラーまたはスキーマを変更します。
cargo web check を実行します：gen-api が新しい仕様から api-generated.ts を再生成し、その後 tsc -b がそれに対してダッシュボードの型チェックを行います。削除されたフィールドに依存しているコンシューマーはコンパイルに失敗します。
web/src/ 内のコンシューマーを一致するように更新します。
cargo web build で最終バンドルをビルドします。

CIとリリースビルド

必須の CI ゲートでは、ダッシュボード、そのツールチェーン、エクスポートされるスキーマを担当する Rust クレート（zeroclaw-config、zeroclaw-gateway、zeroclaw-runtime、zeroclaw-sop-graph）、xtask ジェネレーター、ワークスペースのマニフェスト、またはこのワークフローに変更があった場合に cargo web check を実行します。これにより、無視対象の TypeScript クライアントを再生成し、バンドルを生成せずにダッシュボードの型チェックを行います。Rust の lint/build/test ジョブでは、バンドルなしでゲートウェイクレートをコンパイルできるよう、引き続き web/dist/.gitkeep プレースホルダーを使用します。ダッシュボードを含むリリース成果物の生成は別の手順です：

sh

cargo web build
cargo build --release --features gateway

ゲートウェイは実行時に static_files.rs を介してファイルシステムから web/dist/ を読み込むため、Rust のコンパイルと web ビルドは分離されています。ダッシュボードを提供するインストール環境では、生成済みの web/dist/ をバイナリと一緒に同梱してください。

必要なツール

ツール	インストール
`npm`	https://nodejs.org/ またはリポジトリのルートで `nvm install && nvm use`
`cargo`	https://rustup.rs

リポジトリのルートにある .nvmrc は、リリース用 Web ビルドで使用する Node のメジャーバージョンを固定します。ローカルでのダッシュボード作業にもこれを使用することで、npm install、cargo web check、手動でのリリースビルドのすべてが同じ Node 系列で実行されるようになります。

npm がない場合、cargo web はインストールのヒントを表示してすぐに失敗します。

対応ブラウザ（最小バージョン）

ダッシュボードは、color-mix() と structuredClone() の両方をサポートするエバーグリーンブラウザを対象としています。

Chrome 111以降
Edge 111+
Firefox 113以降
Safari 16.2+

Keyboard shortcuts

ZeroClaw Docs