Web Frontend

<Modal
  open
  dismissible
  => (!next ? onClose() : undefined)}
  title="Change sampling rate"
  description="Percentage of incoming traces this evaluation runs against."
  footer={
    <>
      <CloseTrigger />
      <Button => void form.handleSubmit()}>Save</Button>
    </>
  }
>
  <form fields */}</form>
</Modal>

Reach for the composition form (Modal.Root / Modal.Content / Modal.Header / Modal.Body / Modal.Footer) only when the short form can't express what you need:

• Custom header JSX beyond a string title + description — render <Modal.Header>{custom JSX}</Modal.Header> directly.
• Multiple body regions, or content that must opt out of the standard body padding / scroll.
• Conditional rendering of header or footer that can't be driven by passing undefined.

Notes:

• dismissible defaults to false — pass it to show the close X.
• scrollable defaults to true. For short bodies that shouldn't grow to fill height, pass scrollable={false}.
• Do not wrap your children in your own <Modal.Body> while using the short form — children are already wrapped, double-wrapping nests padding.

Route-level component organization

Place React components close to the routes that use them, inside a -components/ subfolder within the route directory. This keeps route files (which TanStack Router auto-discovers) clearly separated from supporting components.

routes/_authenticated/projects/$projectId/datasets/
├── index.tsx                       # route file
├── $datasetId.tsx                  # route file
└── -components/                    # supporting components for these routes
    ├── dataset-table.tsx
    ├── row-detail-panel.tsx
    └── version-badge.tsx

• Route files live directly in the route directory — TanStack Router discovers them
• Supporting UI for those routes lives in the adjacent -components/ folder
• domains/ directories (apps/web/src/domains/) are for state management only: server functions (writes) and collections/queries (reads) — not UI components

Design system showcase

• When adding a new implemented UI component in packages/ui (or replacing a placeholder export with a real implementation), update apps/web/src/routes/design-system.tsx to include a usage example for that component in both light and dark mode previews.
• Treat apps/web/src/routes/design-system.tsx as the canonical visual inventory for @repo/ui components.

State management (TanStack)

The web app uses a server-centric, query-driven architecture built on the TanStack ecosystem. No Zustand, Redux, or global stores.

Server functions — All data fetching and mutations use createServerFn from @tanstack/react-start:

import { Effect } from "effect"
import { ProjectRepository, createProjectUseCase } from "@domain/projects"
import { ProjectRepositoryLive, SqlClientLive } from "@platform/db-postgres"
import { getPostgresClient } from "../../server/clients.ts"

// Query (GET)
export const listProjects = createServerFn({ method: "GET" }).handler(async () => {
  const { organizationId } = await requireSession()
  const client = getPostgresClient()

  return await Effect.runPromise(
    Effect.gen(function* () {
      const repo = yield* ProjectRepository
      return yield* repo.findAll()
    }).pipe(
      Effect.provide(ProjectRepositoryLive),
      Effect.provide(SqlClientLive(client, organizationId)),
    ),
  )
})

// Mutation (POST) with Zod validation
export const createProject = createServerFn({ method: "POST" })
  .inputValidator(createProjectSchema)
  .handler(async ({ data }) => {
    const { userId, organizationId } = await requireSession()
    const client = getPostgresClient()

    return await Effect.runPromise(
      createProjectUseCase({...}).pipe(
        Effect.provide(ProjectRepositoryLive),
        Effect.provide(SqlClientLive(client, organizationId)),
      ),
    )
  })

Server functions live in apps/web/src/domains/*/functions.ts.

Collections — Client-side reactive state uses TanStack React DB + Query via queryCollectionOptions:

const projectsCollection = createCollection(
  queryCollectionOptions({
    queryClient,
    queryKey: ["projects"],
    queryFn: () => listProjects(),
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => { /* optimistic insert */ },
    onUpdate: async ({ transaction }) => { /* optimistic update */ },
    onDelete: async ({ transaction }) => { /* optimistic delete */ },
  }),
)

export const useProjectsCollection = (...) => useLiveQuery(...)

Collection files live in apps/web/src/domains/*/collection.ts.

Route middleware vs route data

• Use beforeLoad for middleware-style checks that should block the route tree early: auth redirects, authorization gates, and other preconditions.
• Use loader for data the route or layout actually renders. This keeps rendered data in TanStack Router's loader lifecycle, so it can use staleTime, useLoaderData({ select }), and avoid unnecessary refetching on same-route search-param navigations.
• If the same lookup is both your guard and your rendered data source, prefer doing that work in loader once instead of duplicating it across beforeLoad and loader.
• When multiple descendant routes need parent loader data, prefer a small route-scoped wrapper around getRouteApi("...") instead of repeating the route id string in every file.

export const Route = createFileRoute("/admin")({
  beforeLoad: async () => {
    const session = await getSession()
    if (!session?.user.isAdmin) throw redirect({ to: "/" })
  },
})

export const Route = createFileRoute("/_authenticated")({
  staleTime: Infinity,
  loader: async () => {
    const session = await getSession()
    if (!session) throw redirect({ to: "/login" })

    const sessionData = session.session as Record<string, unknown>
    const organizationId =
      typeof sessionData.activeOrganizationId === "string" ? sessionData.activeOrganizationId : null
    if (!organizationId) throw redirect({ to: "/welcome" })

    return {
      user: session.user,
      organizationId,
    }
  },
})

const authenticatedRoute = getRouteApi("/_authenticated")

export function useAuthenticatedUser() {
  return authenticatedRoute.useLoaderData({ select: (data) => data.user })
}

Key rules:

• Server functions are the only data-fetching mechanism — no direct REST API calls from the client
• Use collections for reactive, queryable client state with automatic server sync
• Use useState for local UI state (modals, form visibility); no global stores
• Invalidate query cache after mutations: getQueryClient().invalidateQueries({ queryKey: [...] })
• Forms use TanStack React Form (useForm + form.Field)

Navigation: <Link> vs useNavigate

Rule: if navigation is triggered by a user clicking something, render a <Link> (from @tanstack/react-router). Reserve useNavigate for programmatic redirects — work the user didn't directly click "go there" for.

A real anchor (<Link> → <a href>) is the only way to get:

• href (hover-preview the URL, right-click → copy/open, browser history correctness)
• cmd/ctrl-click and middle-click to open in a new tab
• Keyboard activation (Enter) and focus-visible handling for free, no manual onKeyDown
• Works before client-side JS has hydrated

Anti-pattern to avoid

Do not put role="button", onClick, and a hand-rolled onKeyDown on a Badge/div/span to call navigate(...). That re-implements (badly) what <Link> already provides, and silently breaks cmd-click / middle-click / right-click flows.

// ❌ Bad — click-to-navigate via useNavigate
const navigate = useNavigate()
function open() {
  navigate({ to: "/projects/$projectSlug/settings/flaggers", params: { projectSlug }, search: { flagger: slug } })
}
return (
  <Badge
    role="button"
    tabIndex={0}
   
    => (e.key === "Enter" || e.key === " ") && open()}
  >
    {label}
  </Badge>
)

// ✅ Good — real anchor wraps the visual badge
return (
  <Link
    to="/projects/$projectSlug/settings/flaggers"
    params={{ projectSlug }}
    search={{ flagger: slug }}
    aria-label={`Open the ${name} flagger settings`}
    className="inline-flex"
  >
    <Badge variant="secondary" size="small" className="cursor-pointer hover:bg-muted">
      {label}
    </Badge>
  </Link>
)

Badge (and other @repo/ui primitives that are plain <div>s without asChild) should be wrapped inside the <Link> as visual children — the <Link> is the interactive anchor.

For <Button> (which does support asChild), use the Radix Slot pattern: <Button asChild><Link to="…">…</Link></Button>.

When the clickable element sits inside a larger row-level click handler, add data-no-navigate to the <Link> (the parent handler skips elements under [data-no-navigate]) and onClick={(e) => e.stopPropagation()} for belt-and-suspenders.

Table rows that navigate

If clicking an InfiniteTable row opens a different page, use the renderRowLink prop — not onRowClick + useNavigate. renderRowLink is router-agnostic: the table renders a stretched-link overlay, the app supplies the <Link> element.

<InfiniteTable
  data={items}
  columns={columns}
  getRowKey={(r) => r.id}
  renderRowLink={(row, props) => (
    <Link to="/items/$id" params={{ id: row.id }} aria-label={`Open ${row.name}`} {...props} />
  )}
/>

Keep onRowClick only for same-route row interactions: selecting a row to open a drawer, applying a saved filter on the same page, toggling expansion state, etc. — the cases where there is no new URL to navigate to.

Command palette (Cmd+K)

The global command palette (apps/web/src/components/command-palette/, mounted in _authenticated.tsx) is the keyboard launcher for navigation, actions, contextual entity actions, and in-project search. Full design + maintenance guide: dev-docs/command-palette.md — read it before changing palette behavior.

Keep it in sync when you add UI. Anything navigable or actionable should also be reachable from the palette:

• New project section / settings page → add it to apps/web/src/domains/projects/project-sections.ts. The sidebar, settings sub-nav, and the palette navigation all consume that module, so it surfaces everywhere automatically — don't hardcode a nav entry in the palette.
• New global action → add a command to command-palette/commands/use-global-commands.tsx (switch/navigate actions rank above create actions; keep Log out last).
• New action on an entity with a detail view (issue/trace drawer, etc.) → contribute it from that view with useRegisterCommands(...) (section: "context", a group label, reusing the view's existing handler).
• New searchable entity → add a commands/use-*-search-commands hook gated on useCurrentProject() + a non-empty query, then wire a group into command-palette.tsx.

The palette runs cmdk with shouldFilter={false} and filters in React — never rely on cmdk's built-in keywords/filter for query-driven rows (cmdk snapshots keywords on first registration). See the dev-doc for the rationale.

TanStack Form + Zod field errors (createFormSubmitHandler + fieldErrorsAsStrings)

When: useForm submits work that can fail with Zod validation (for example server functions using inputValidator), and you want inline errors on @repo/ui fields (not only a toast).

Module: apps/web/src/lib/form-server-action.ts

Always use both when you want Zod-driven field errors: the submit handler wires errors into form state; the helper wires form state into @repo/ui.

Do not duplicate the inline pattern field.state.meta.errors.length > 0 ? field.state.meta.errors.map(String) : undefined — use fieldErrorsAsStrings instead.

Reference: apps/web/src/routes/_authenticated/index.tsx — RenameProjectModal: createFormSubmitHandler in useForm (line 225), fieldErrorsAsStrings on the name field Input (line 287).

Layout and spacing

• Always use flexbox for layout (flex, flex-col, flex-row)
• Never use margin utilities (no m-*, mx-*, my-*, mt-*, etc.)
• Always use gap utilities for spacing between elements (gap-*, gap-x-*, gap-y-*)
• Always use p-* (padding) for internal spacing within containers

Conditional classes (cn)

With cn(), use object syntax { "class-name": condition } — not short-circuit condition && "class-name".

// ❌ Bad
<div className={cn("base-class", isActive && "bg-accent")} />

// ✅ Good
<div className={cn("base-class", { "bg-accent": isActive })} />

Example

// ❌ Bad - using margins and space-y
<div className="space-y-4 mt-4">
  <div className="mb-2">Item 1</div>
  <div className="mb-2">Item 2</div>
</div>

// ✅ Good - using flexbox with gap
<div className="flex flex-col gap-4 pt-4">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

React effects (useEffect policy)

• Do not call useEffect directly in components; use useMountEffect from @repo/ui for mount/unmount-only sync (listeners, imperative widgets, one-time setup).
• If raw useEffect is unavoidable, add TODO(frontend-use-effect-policy) with a short reason.

Prefer: derive values during render; run work in event handlers; controlled vs uncontrolled via value !== undefined; reset by key when an entity id changes.

Avoid: deriving state from props in an effect; fetching in effects to set state; mirroring props into local state; effects as command dispatchers.

import { useMountEffect } from "@repo/ui"

useMountEffect(() => {
  const cleanup = subscribeToExternalSystem()
  return () => cleanup()
})