---
title: React Frontend
description: WebUI frontend layout, routing, shared API contracts, state management, localization, and testing pipelines.
updated: 2026-10-20
---

# React Frontend

The frontend is a single-page application built with React and Vite, served as static files by `gui.py`. It contains no server-side rendering and requires no Node.js runtime in production.

## <DocIcon name="wrench" /> Technology Stack

| Library | Version | Role |
| --- | --- | --- |
| React | 19.3 | Component framework |
| React Router | 7.18 | Client-side routing |
| Vite | 6.x | Development server and bundler |
| TypeScript | 5.x | Type checking |
| ECharts | 6.1 | Data visualization |
| @xyflow/react | 12.x | Visual node scheduler canvas |
| motion | 13.x | Animation transitions |
| CodeMirror | 6.x | Embedded YAML / JSON editors |
| lucide-react | 1.45 | Iconography |

Requires Node.js `>=22.12.0` (defined in `frontend/package.json` under `engines`).

## <DocIcon name="folder" /> Directory Architecture

```text
frontend/src/
├── main.tsx           # App entry and router configuration
├── app/               # Layout chrome, navbar, search index, preferences
├── pages/             # Page view components
├── components/        # Reusable design system components
├── api/               # WebSocket client, types, generated contracts
├── config/            # Dynamic form models and edit queue
├── scheduler/         # Visual graph nodes, ports, layout algorithms
├── mind/              # Mind calculator modules
├── fleet-tech/        # Fleet technology views
├── resources/         # Resource flow analytics
├── stock/             # Stock exchange interfaces
├── remote/            # Remote pairing dialogs
├── i18n*.ts           # Localization strings and dev utilities
└── styles/            # Global stylesheets and theme tokens
```

## <DocIcon name="map" /> Client-Side Routes

| Path | View |
| --- | --- |
| `/` | Home dashboard (instance list) |
| `/announcement` | Announcements |
| `/interface` | Interface preferences |
| `/remote` | Remote access settings |
| `/settings` | System settings |
| `/updater` | Upstream updater |
| `/configs` | Instance management |
| `/dev` | Developer utilities |
| `/i/:instance/overview` | Instance overview |
| `/i/:instance/task/:task` | Task configuration forms |
| `/i/:instance/statistics` | Performance and drop statistics |
| `/i/:instance/stock-exchange` | Stock exchange ledger |
| `/i/:instance/task/SchedulerProgram` | Visual scheduler canvas |
| `/i/:instance/task/MindCalculator` | Mind calculator |
| `/i/:instance/task/FleetTechnology` | Fleet technology |

Legacy routes (`/logs`, `/resources`, `/scheduler`, `/mind-calculator`) redirect to preserve existing bookmarks.

## <DocIcon name="plug" /> Consuming API Contracts

```ts
import { api } from '../api/client'

const list = await api.request('instances.list', {})
```

- `frontend/src/api/generated.ts` is generated by `dev_tools.export_api_schema`, defining method names and request/response interfaces.
- `frontend/src/api/contract.json` provides a comprehensive JSON Schema for automated validation.
- **Never edit generated files manually**. Re-export schemas when backend endpoints change.

`api.request` handles request ID generation, timeouts, error code mapping, and reconnection prompts.

## <DocIcon name="box" /> State Architecture

State is partitioned across three layers:

| Layer | Implementation | Scope |
| --- | --- | --- |
| Server State | Subscriptions + RPC results | Instance status, resource gauges, telemetry |
| Edit State | `config/EditQueue.ts` | Uncommitted configuration adjustments |
| UI State | localStorage + navbar state | Themes, density settings, navigation routes |

### Configuration Edit Queue

Form adjustments do not dispatch network requests per keystroke:

1. Input changes register in `EditQueue`.
2. Edits to identical paths coalesce.
3. Batched changes commit via `config.patch` with `revision` checks.
4. Concurrent conflicts prompt users to reload without overwriting external edits.

View teardown awaits queue flushing to prevent data loss on rapid navigation.

## <DocIcon name="message-text" /> Localization (i18n)

- `i18n.resources.ts` manages runtime strings, with `zh-CN` as the baseline locale.
- `i18n.dev.ts` flags missing keys in development environments.
- Task parameter descriptions load from `module/config/i18n/*.json` via `schema.get`.

When authoring new UI views, provide both `zh-CN` and `en-US` strings.

## <DocIcon name="zap" /> Visual Scheduler Canvas

Modules under `src/scheduler/` power the custom visual scheduler:

- Node schemas derive from `module/scheduler/` models; the frontend handles layout and editing.
- Square ports govern sequence ordering; round ports handle typed data flow.
- Canvas state is managed by React Flow, committing modifications to the document model.
- Edits validate via `scheduler.program.validate` before applying.

## <DocIcon name="rainbow" /> Styling Conventions

- Global CSS design tokens reside in `styles/`.
- Theme toggles consume CSS variables; avoid hardcoding hex colors inside components.
- Responsive breakpoints collapse navigation sidebars into single-column layouts on mobile viewports.

## <DocIcon name="laptop" /> Local Frontend Development

```bash
npm ci --prefix frontend
npm run dev --prefix frontend        # Connects to live backend on port 25548
npm run dev:mock --prefix frontend   # Runs against mock service without live backend
```

The Vite server binds to `127.0.0.1`, proxying requests to the backend. `dev:mock` enables UI authoring without risk to live configurations.

## <DocIcon name="flask" /> Testing Suites

| Suite | Command | Scope |
| --- | --- | --- |
| Type Check | `npm run typecheck --prefix frontend` | TypeScript type evaluation |
| Unit Tests | `npm test --prefix frontend` | Components, hooks, utilities |
| End-to-End | `npm run test:e2e --prefix frontend` | Live backend testing |
| Mock End-to-End | `npm run test:e2e:mock --prefix frontend` | Mock service testing |
| Stock Exchange | `npm run test:e2e:stock --prefix frontend` | Stock trade workflows |

## <DocIcon name="package" /> Production Builds

```bash
npm run build --prefix frontend
```

- Runs `tsc -b` followed by `vite build`; compilation errors fail the build immediately.
- Outputs compile to `frontend/dist`, served statically by `gui.py`.