Construyendo el panel web

El panel web en web/ es una aplicación Vite + React + TypeScript. Su cliente de API en TypeScript se genera a partir de la especificación OpenAPI en tiempo de ejecución del gateway, no se escribe a mano.

Inicio rápido

sh

cargo web build         # bundle de producción en web/dist/
cargo web dev           # servidor de desarrollo vite con HMR
cargo web check         # solo typecheck (gen-api + tsc -b)
cargo web gen-api       # regenerar web/src/lib/api-generated.ts
cargo web install       # npm install en web/

cargo web es un alias de cargo run -p xtask --bin web -- (definido en la configuración de cargo). Cada subcomando ejecuta automáticamente npm install si falta web/node_modules/.

Qué se genera

Ruta	Generador	¿Rastreado?
`web/src/lib/api-generated.ts`	`cargo web gen-api`	gitignored
`target/openapi.json`	`cargo web gen-api`	gitignored
`web/dist/`	`cargo web build`	gitignored

cargo web gen-api renderiza la especificación OpenAPI en el propio proceso desde zeroclaw_gateway::openapi::build_spec(), la escribe en target/openapi.json y pasa ese archivo a openapi-typescript. El mismo build_spec() sirve /api/openapi.json en tiempo de ejecución, por lo que build_spec() es la única fuente del contrato y los archivos generados se reconstruyen bajo demanda.

Flujo de edición

Cambia un handler de gateway o un schema en crates/zeroclaw-gateway/.
Ejecuta cargo web check: gen-api regenera api-generated.ts a partir de la nueva especificación, luego tsc -b verifica los tipos del dashboard contra ella. Cualquier consumidor que dependa de un campo ahora eliminado falla al compilar.
Actualiza los consumidores en web/src/ para que coincidan.
cargo web build para el paquete final.

Compilaciones de CI y de versión

La comprobación obligatoria de CI ejecuta cargo web check cuando cambian el panel, su cadena de herramientas, los crates de Rust responsables de los esquemas exportados (zeroclaw-config, zeroclaw-gateway, zeroclaw-runtime y zeroclaw-sop-graph), el generador xtask, los manifiestos del espacio de trabajo o este flujo de trabajo. Esto vuelve a generar el cliente de TypeScript ignorado y comprueba los tipos del panel sin producir un paquete. Los trabajos de lint/compilación/pruebas de Rust siguen usando un marcador de posición web/dist/.gitkeep para que el crate de gateway pueda compilarse sin el paquete. Generar un artefacto de lanzamiento que incluya el panel es un paso independiente:

sh

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

El gateway carga web/dist/ desde el sistema de archivos en tiempo de ejecución mediante static_files.rs, por lo que la compilación de Rust y la compilación web están desacopladas. Distribuye el web/dist/ poblado junto con el binario para las instalaciones que deban servir el dashboard.

Herramientas requeridas

Herramienta	Instalar
`npm`	https://nodejs.org/ o `nvm install && nvm use` desde la raíz del repositorio
`cargo`	https://rustup.rs

El .nvmrc de la raíz del repositorio fija la versión principal de Node utilizada por las compilaciones web de release. Úsalo para el trabajo local del dashboard para que npm install, cargo web check y las compilaciones manuales de release se ejecuten todas con la misma línea de Node.

cargo web falla rápidamente con una sugerencia de instalación si npm no está presente.

Navegadores compatibles (mínimo)

El panel está orientado a navegadores evergreen compatibles con color-mix() y structuredClone().

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

Keyboard shortcuts

ZeroClaw Docs