---

name: frontend-feature
description: Use when building or modifying pages, components, modules, routes, data loading, forms, API integration, or UI features — including small changes like a column, filter, or panel — in the orchestration cluster webapp (webapp/client/apps/orchestration-cluster-webapp/).

---

# Frontend Feature Development

Reference for building features in `@camunda/orchestration-cluster-webapp` — the unified React frontend replacing Operate, Tasklist, and Admin. The app uses React 19, TypeScript, Vite, TanStack Router (file-based), TanStack Query, MobX (theme + session), Carbon Design System, and SCSS.

## Key rules

- Use Carbon Design System components (`@carbon/react`). Introducing alternative UI libraries fragments the design language and creates maintenance burden.
- Use `#/` path aliases for all imports. Each pod has its own alias; shared infrastructure has one too:
  - `#/operate/*` → `src/operate/` (Operate pod)
  - `#/tasklist/*` → `src/tasklist/` (Tasklist pod)
  - `#/admin/*` → `src/admin/` (Admin pod)
  - `#/shared/*` → `src/shared/` (cross-pod shared code)
- Prefer **types** from `@camunda/camunda-api-zod-schemas` to type API responses — trust the API contract. Use Zod schema validation only for **user input** (forms, URL search params, path params). For general validation needs beyond API contracts, use Zod directly.
- Pod areas (`src/operate/`, `src/tasklist/`, `src/admin/`) are **autonomous** — pods decide their own internal folder structure, naming conventions, and patterns. Do not prescribe internal layout for another pod's area.
- `src/shared/` holds cross-cutting infrastructure (http, auth, config, errors, theme, i18n, tracking, feature flags). Changes here affect all pods; keep shared code focused and small.
- Route files live in `src/routes/_auth/{pod}/` and are **thin wrappers**: they wire the pod's page component into the router. No feature logic in route files.
- Use a single `export {}` block at the end of each file — no inline `export` on declarations. Only export symbols that are actually imported by other files. Don't export internal helpers, types used only within the same file, or constants that nothing else references. This keeps the public surface minimal and scannable.
- YAGNI — don't build abstractions for hypothetical future use. Three similar lines beat a premature wrapper. Wait until a real requirement forces the shape.

## Code style

- **Booleans**: prefix with `is` (e.g., `isLoading`, `isVisible`).
- **Constants**: `SCREAMING_SNAKE_CASE` (e.g., `MAX_RETRY_COUNT`).
- **Components**: `PascalCase` (e.g., `DashboardHeader`).
- **Pages**: `PascalCase` + `Page` suffix (e.g., `DashboardPage`); co-located styles and tests use the same name (`DashboardPage.module.scss`, `DashboardPage.test.tsx`).
- **Comments**: avoid them. Code should explain itself. When a comment is necessary, explain *why*, not *how*.
- **Memoize derived data**: when creating new values inside a component (e.g., `.map()`, `.filter()`, transformations), always wrap in `useMemo` to avoid recomputing on every render.
- **SCSS spacing**: use Carbon design token CSS variables for spacing (e.g., `$spacing-05`, `var(--cds-spacing-05)`). Never hardcode pixel or rem values for layout spacing.

## Building a feature

A feature lives in the pod's area and plugs into the shared router:

1. **Pod area** (`src/{operate,tasklist,admin}/`) — build your page component and any supporting code here. Internal structure (folder names, conventions, depth) is the pod's decision. Reuse existing shared modules before creating new ones in the pod area.
2. **`src/shared/`** — for cross-cutting concerns used by more than one pod: http, auth, config, errors, theme, i18n, tracking, feature flags. Keep shared code focused; one module per concern.
3. **`src/routes/_auth/{pod}/`** — thin route file. File path = URL path. Auth-gated routes go under `_auth/`. The route owns the loader, `pendingComponent`, and `errorComponent`. It imports the page component from the pod area.

Default to a new route for anything a user can navigate to. Skip a route only for transient overlays (toasts, hover cards), non-linkable modals (confirmations), or in-page tabs sharing the same data (encode as `?tab=...` search param).

## URL as state

The URL holds the page's state. Components read from it, not from each other.

- **Route params**: entity identity (`/_auth/processes/$processKey`).
- **Search params**: view state — filters, sort, cursor, selection, active tab, modal-open flag.
- **Local React state**: ephemeral UI only — open menu, input draft, hover, focus.

Validate all URL inputs with Zod. Use `validateSearch` for search params and `parseParams` for path params. Reuse schemas from `@camunda/camunda-api-zod-schemas` when the URL slice maps to an API contract; otherwise co-locate the schema in the route file.

## Data loading

Uses TanStack Router loaders + TanStack Query. Three tiers in descending order of preference:

1. **Route loader + suspense queries** — `queryClient.ensureQueryData` in the loader, `useSuspenseQuery` in the component. Same `queryOptions` constant for both.
2. **Route loader + `pendingComponent`** — same as above, but fire-and-forget the loader (don't `await`) and add a `pendingComponent` skeleton so the page doesn't freeze.
3. **Streamed promises + granular skeletons** — `await` the fast query, fire-and-forget the slow one, wrap the slow slice in its own `<Suspense>`.

`queryOptions` constants live in `#/shared/http/queries.ts` — the central query dictionary. API endpoint definitions (URL + method + types) live in `#/shared/http/endpoints.ts`. Do not co-locate queries or endpoints with individual pod areas; keep them in one place so the full set is visible and discoverable. Error handling defaults to `errorComponent` on the route. 401s are handled centrally by the `request()` wrapper (cache clear + login redirect).

## Before starting a feature

Work through these Camunda-specific considerations. They shape the page architecture:

- **API schemas**: check if the endpoints exist in `@camunda/camunda-api-zod-schemas`. If not, add them as part of your work.
- **Pagination**: most list endpoints paginate. Default to infinite scroll with `useSuspenseInfiniteQuery`. Trust `hasMoreTotalItems`, not `totalItems`. Prefer cursor-based pagination over offset for performance.
- **Permissions**: authorization is server-side. For actions, leave the button visible; surface a toast on 403. For data loads, render a forbidden state (page-level or section-level). A 403 can also mean a feature is disabled for the deployment.
- **Eventual consistency**: reads from secondary storage are eventually consistent. If the OpenAPI spec flags `x-eventually-consistent`, poll with `refetchInterval`. Default to pessimistic UI — reach for optimistic updates only with an explicit reconciliation plan.
- **Batch operations**: POST returns a `batchOperationKey`. Poll `GET /v2/batch-operations/{key}` for state. Show a toast confirming submission, poll in the background, surface the result when it lands. Never block the page on the poll.
- **Multi-tenancy**: deployment-level toggle. Render tenant picker, columns, and filters only when it's on. Always pass the active tenant in requests when enabled.

## Forms

Decision rule: use plain HTML `<form>` for simple forms. Reach for react-final-form when the form needs schema-based validation or form/field meta state (`dirty`, `touched`, submission state, field arrays). Validate on submit (whole form) and on blur (single field) — never on every keystroke. Reuse Zod schemas from `@camunda/camunda-api-zod-schemas` where the form maps to an API contract.

## Feature flags

When a feature is not ready for users but code needs to merge to `main`, gate it behind a flag. Export a boolean `const` from `src/shared/feature-flags.ts`, `SCREAMING_SNAKE_CASE`, default `false`. Gate at the highest possible level — route, page, or nav item — not deep inside a pod area. Remove flags in a dedicated cleanup PR once the feature ships.

## Local checks before commit

Run these commands:

    # From webapp/client/
    npm run prettier:format  # Auto-format with Prettier (always use this script, never npx prettier)
    npm run lint             # ESLint + Prettier + Knip (workspace; Knip fails on unused exports/dependencies)

    # From webapp/client/apps/orchestration-cluster-webapp/
    npm run typecheck        # TypeScript across all tsconfigs (always use this script, never npx tsc)
    npm run test:unit        # Vitest browser mode (headless Chromium)

## Canonical docs

- `docs/monorepo-docs/frontend/orchestration-cluster-webapp.md` — tech stack, layout, scripts, testing overview.
- `docs/monorepo-docs/frontend/data-loading.md` — TanStack Router + Query patterns with full examples.
- `docs/monorepo-docs/frontend/forms.md` — form library guidance.
- `docs/monorepo-docs/frontend/development-process/creating-a-new-page.md` — step-by-step with checklist.
- `docs/monorepo-docs/frontend/development-process/before-starting.md` — pre-feature considerations.
- `docs/monorepo-docs/frontend/development-process/extending-an-existing-page.md` — incremental changes.
- `docs/monorepo-docs/frontend/development-process/working-on-large-feature.md` — PR splitting and feature flags.
- `docs/monorepo-docs/frontend/code-style.md` — naming, exports, comments.