frontend-migrator

name: frontend-migrator description: Use when migrating, porting, or rewriting frontend code from operate/client/ or tasklist/client/ to the orchestration cluster webapp. Trigger when migrating legacy pages/components, converting React Router to TanStack Router, replacing MobX with TanStack Query, rewriting styled-components as SCSS, converting legacy tests to Vitest browser mode, or asking how a legacy pattern maps to the new app.

Frontend Migration: Legacy to Orchestration Cluster Webapp

The orchestration cluster webapp (webapp/client/apps/orchestration-cluster-webapp/) is replacing the legacy Operate, Tasklist, and Admin frontends. Migration is a rewrite using new patterns, not a code port. The legacy code is the specification of what the feature does; the new code follows a different architecture for how.

This skill is the translation layer. It maps legacy patterns to their target equivalents so you produce code that fits the new codebase from the start. For target conventions (pod areas + shared structure, data loading tiers, forms, feature flags), defer to the frontend-feature skill. For test-writing details, defer to frontend-unit-test and frontend-integration-test.

Migration workflow

1. Understand the legacy feature's intent

Read the legacy code and extract what it does for users, not how it's implemented. Identify:

• What data does it display? Where does that data come from (which API endpoints)?
• What actions can the user take? What side effects do those actions trigger?
• What URL does the page live at? What parameters does it accept?
• What states does it handle? (loading, empty, error, forbidden, pagination)

Focus on behavior. The implementation details (MobX stores, styled-components, React Router hooks) are all going to change.

2. Check API endpoint availability

Look up every endpoint the legacy feature calls in @camunda/camunda-api-zod-schemas. The legacy code typically imports from this package already — check its import statements. If an endpoint is missing from the schema package, it needs to be added before or alongside the migration.

3. Map to pod area / shared / routes

Decide how the feature decomposes in the new architecture. The general rule:

• One route file per navigable URL, under src/routes/_auth/<pod>/
• Page component and supporting code in the pod's area (src/operate/, src/tasklist/, or src/admin/). The pod decides its own internal structure — there is no prescribed layout.
• Shared cross-cutting code in src/shared/<concern>/ — http, auth, config, errors, i18n, theme, tracking. Use what's already there; extend it rather than duplicating in the pod area.

Produce the code directly. If the decomposition is genuinely ambiguous (e.g., a legacy page that mixes two concerns and could become one page or two), flag it for the user with your recommendation and reasoning.

Dependencies flow one way: routes → pod area → shared. Pod code must never import from a route file. Shared code must never import from a pod area. If a type (like search param schemas) needs to be shared between a route and pod code, define it in the pod area and import it into the route — not the other way around.

4. Transform patterns

This is the core of the migration. Each legacy pattern has a target equivalent — apply them systematically. The summary is below; see references/pattern-mapping.md for side-by-side code examples.

5. Write tests

Rewrite tests using the new patterns (Vitest browser mode, MSW via worker fixture, expect.element()). Don't port legacy test code — the testing infrastructure is fundamentally different. See the testing transformation table below and references/pattern-mapping.md for full before/after examples.

6. Run local checks

# From webapp/client/
npm run prettier:format  # Auto-format (always use this script, never npx prettier)
npm run lint

# 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

Pattern transformations

Routing

Auth-gated routes go under _auth/ (pathless layout route). Product routes go under _auth/operate/, _auth/tasklist/, or _auth/admin/.

Data fetching

The pattern is: define the endpoint in endpoints.ts, wrap it in queryOptions in queries.ts, prefetch in the route loader, consume with useSuspenseQuery in the pod page component. This replaces the legacy pattern where each feature scattered its own query hooks.

State management

This is where most legacy code diverges from the target. Legacy apps use MobX stores for everything — server cache, UI state, filters, form drafts. The target splits state across purpose-built mechanisms:

When you encounter a MobX store in legacy code, don't port it. Decompose it by asking: "Would a user want to bookmark or share this state?" If yes → URL. If it's server data → TanStack Query. If it's ephemeral → useState.

Styling

SCSS modules use dot notation for class access: className={styles.container}.

Component structure

Error handling

Testing

This is the biggest divergence. Legacy tests use jsdom + Testing Library globals + vi.mock(). The target uses a real Chromium browser + MSW-only mocking + no global screen.

Endpoint mocks live in shared-test-modules/mock-handlers.ts. If the mock you need doesn't exist, add it there using createEndpointMock() — never create mocks inline in test files.

i18n

Legacy (Operate): No i18n — all strings are hardcoded in English. There are no i18next imports, translation files, or useTranslation() calls.

Target: The orchestration cluster webapp uses i18next + react-i18next. When migrating from Operate, wrap user-facing strings in t('key') via useTranslation() and add translation keys to the appropriate namespace in src/shared/i18n/. Check the target's namespace structure before adding keys.

Handling partial migrations

Not every migration is a full page. You might be adding a single component, column, filter, or panel to a page that already exists in the orchestration webapp.

For partial work:

• Skip route creation — the route already exists
• Check if a module already exists for the concern — extend it rather than creating a new one
• Follow the same pattern transformations for the piece you're adding
• If the page component needs new data, add the query to queries.ts and the endpoint to endpoints.ts

Common pitfalls

Porting MobX stores verbatim. This is the most common mistake. Legacy stores mix server cache, UI state, and derived data in one class. In the target, these concerns are separated. Decompose the store, don't port it.

Scattering query definitions. Legacy apps have use*.query.ts files next to each feature. The target centralizes all queries in #/shared/http/queries.ts and all endpoints in #/shared/http/endpoints.ts. This makes the full API surface visible in one place.

Using vi.mock(). Legacy tests mock MobX stores and modules with vi.mock(). The target mocks HTTP responses with MSW. If you need to control what a component sees, control it at the network level. The only acceptable use of vi.mock() is for things like vi.useFakeTimers() where there's no HTTP-level alternative.

Creating inline MSW handlers in test files. Don't write http.post('*/v2/...', () => HttpResponse.json(...)) directly in tests. All endpoint mocks must be defined in shared-test-modules/mock-handlers.ts using createEndpointMock() and consumed via worker.use(mockXxxEndpoint({successResponse: ...})). If the mock you need doesn't exist yet, add it to shared-test-modules/mock-handlers.ts — never inline it.

Using waitFor or findBy*. These don't exist in Vitest browser mode. Use await expect.element(...) which retries automatically.

Creating barrel files. The target doesn't use index.ts barrel files. Import files directly using #/ path aliases.

Putting fetch logic in page components. Data fetching belongs in route loaders (beforeLoad or loader). Page components consume data via useSuspenseQuery, they don't initiate fetches.

Using styled-components. Even if the legacy code uses them, the target uses SCSS modules exclusively. Rewrite, don't port.

Checking isLoading / isError on useSuspenseQuery. Unlike useQuery, useSuspenseQuery never returns loading or error states — it suspends the component (handled by <Suspense> or the route's pendingComponent) and throws on errors (handled by errorComponent). If you need inline loading/error handling within a component, use useQuery instead, but prefer useSuspenseQuery with route-level boundaries as the default.

Porting useEffect for navigation. Legacy code uses useEffect(() => navigate(...)) for conditional redirects. The target uses throw redirect() in beforeLoad — it's synchronous relative to the route lifecycle and avoids the flash of the wrong page.

Canonical docs

• docs/monorepo-docs/frontend/orchestration-cluster-webapp.md — tech stack, layout, scripts
• docs/monorepo-docs/frontend/data-loading.md — TanStack Router + Query patterns
• docs/monorepo-docs/frontend/forms.md — form library guidance
• docs/monorepo-docs/frontend/testing.md — unit, integration, a11y, visual testing
• docs/monorepo-docs/frontend/code-style.md — naming, exports, comments
• docs/monorepo-docs/frontend/development-process/creating-a-new-page.md — page creation checklist
• docs/monorepo-docs/frontend/development-process/before-starting.md — pre-feature considerations
• docs/monorepo-docs/frontend/legacy-components.md — legacy app overview + migration epic link
• references/pattern-mapping.md — detailed side-by-side code examples for every transformation