engine / frontend

# Frontend

- Register keyboard shortcuts with `useHotkey` / `useHotkeySequence` from `@tanstack/react-hotkeys`. Do not hand-roll `window.addEventListener("keydown", ...)` handlers. Use the `ignoreInputs` option to skip shortcuts while typing in inputs/textareas/contenteditable instead of checking `e.target.tagName` manually.
- Wrap async user actions (anything with pending/loading/error state) in `@tanstack/react-query` `useMutation`; drive UI with `mutation.isPending` / `mutation.mutate()`. Do not hand-roll a `useState` loading flag with try/catch/setState.
- Show API errors on forms with `showApiErrorOnForm(form, error, fields?)` from `src/lib/form-errors.ts`: set `meta: { hideErrorToast: true }` on the mutation and call it in the submit's `catch`. It puts `errors[].field` on matching fields and toasts the rest. Type the `fields` map with the request's keys (`ApiFieldMap<FormValues, keyof Request>`) so API renames fail to compile.
- Derive state during render instead of syncing it with `useEffect`. Do not use `useEffect` for derived state or as a general escape hatch. If you believe an effect is genuinely unavoidable and cannot find another option, stop and ask the user for guidance before adding one.
- The frontend build embedded into `rivet-engine` must use `pnpm build:engine` / `npx turbo build:engine -F @rivetkit/engine-frontend`, which sets `BASE_URL=/ui/`. Do not compensate for a root `/assets/*` build by adding root asset routes to the engine; fix the embedded build base instead.
- The dashboard serves multiple deployment flavors (cloud / OSS / enterprise) from one build via `features.*`. Test frontend changes in more than one flavor before calling them done. **OSS especially**, since it disables `auth`/`platform`/`acl` and takes different code paths (context switcher, sidebar, onboarding, data providers) that the cloud default never exercises. Switch flavors in the browser console with `localStorage.setItem("FEATURE_FLAGS", "")` (OSS) / `localStorage.removeItem("FEATURE_FLAGS")` then reload. See [Feature flags](../.claude/reference/feature-flags.md#testing-across-flavors-required-for-frontend-changes).
- **OSS and platform (cloud/EE) layouts must not visually diverge.** The same screens take different code paths per flavor (engine vs cloud routes/data providers), but they should look the same. Known parallel pairs that must be kept in sync: the namespace landing (engine [src/app/engine-namespace-landing.tsx](src/app/engine-namespace-landing.tsx) vs cloud [src/app/actors-grid.tsx](src/app/actors-grid.tsx), sharing `ActorBuildCard` / `ActorGridCardSkeleton`) and the namespace settings drawer (one flavor-aware [src/app/settings-drawer.tsx](src/app/settings-drawer.tsx) where engine shows only the Namespace section). When you change one side of a pair, mirror the other, and prefer sharing the presentational component over duplicating markup.
- Engine and cloud namespace index routes both render the Actor-grid landing when no Actor name (`n`) is selected; do not auto-redirect into the first build/actor. Selecting a build sets `n` and shows the Actor list/detail.
- Ship a Ladle story alongside any new UI component, but only when the story would teach something a reader can't see from the component's source or the design system's existing stories. Run with `pnpm dev:ladle` from `frontend/`. Existing example: [src/app/runner-pool-error-popover.stories.tsx](src/app/runner-pool-error-popover.stories.tsx).
  - **Story the integration unit, not the wrapper.** If a component is a thin wrapper over a primitive (e.g. a `<Badge>` with three label variants), do not write a story for it — story the parent that combines it with other state. The interesting states live where data shapes interact: row + cell + tooltip, form + validation + submit. A trivial wrapper's "three near-identical renders" is noise, not coverage.
  - **Drive stories from realistic data fixtures, not prop permutations.** Build fixtures that mirror real API responses (empty result, single item, multi-region, partial failure, mixed kinds). Each story should answer "what does this look like when the backend returns X?" Listing every prop combination produces stories that pass design review but miss bugs like an empty endpoint set falling through to "Multiple endpoints".
  - **Cover the states that produced real bugs in this component.** When you fix a visual bug, the regression case becomes a story. If you can't articulate a state that would change behavior, you don't need another story.
  - **Skip the story if it would require mocking route loaders, auth, or the full data-provider stack.** Either refactor the component to accept its inputs as props (preferred — the story falls out for free), or test it through the parent route in the running dashboard. Do not stub `useLoaderData` / `useRouteContext` inside a story; that path rots fast.
- HTTP responses can be mocked end-to-end in dev via MSW. Append `?mock=1` to any dashboard URL (dev only, gated by `import.meta.env.DEV` in [src/lib/agent-mocks.ts](src/lib/agent-mocks.ts)) to boot the worker. Then in DevTools / agent-browser console: `window.__rivetMock("*/actors/:id/kv/keys/*", { status: 503, body: { group: "guard", code: "service_unavailable", message: "..." } })`. Mocks persist across reloads via sessionStorage; `window.__rivetClearMocks()` resets. Use this to exercise error UIs without standing up real engine state. Prod bundle is unaffected (dynamic `import("msw/browser")` behind the dev gate). To inspect a loading skeleton, add `delayMs` to hold the response open and keep the query pending: `window.__rivetMock("*/actors/names", { status: 200, body: { names: {} }, delayMs: 10000 })`.

More agent context in rivet-dev/engine

20 other files this repository gives its agents.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• rivet-dev/rivet6.3k