Frontend Feature Development

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, 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, 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