Frontend

React & Frontend Coding Guidelines

Verification Commands

Use aube package scripts for frontend checks. From the repo root, prefer aube run -F <package> <script> so commands run against the right frontend package without cd. Do not run npm exec, npx, bare vitest, bare eslint, bare oxfmt, or bare tsc unless you are debugging the package script itself.

For small edits, run the narrowest package script that proves the change. For shared or cross-package frontend changes, run the root aube run lint and aube run type-check scripts.

General Guidelines

• Name the actual state or behavior in identifiers and UI copy, not relative labels such as legacy or modern. For example, use agentIdentityIsNotConfigured for an assistant without an agent identity. Choose the name from the actual condition. Preserve externally contracted values, including metric labels used by queries or alerts, unless the change includes a compatibility plan.

• Use the aube package manager

• When interacting with the server, use the @gram/client package (this is an alias to client/dashboard/src/sdk/src/...)

• The document client/dashboard/src/sdk/REACT_QUERY.md is very helpful for understanding how to use React Query hooks that come with the SDK.

• For data fetching and server state, use @tanstack/react-query instead of manual useEffect/useState patterns

• When invalidating React Query caches after mutations, invalidate ALL relevant query keys — not just the most specific one. Different hooks may use different query key prefixes for the same data (e.g., queryKeyInstance vs toolsets.getBySlug). Use broad invalidation helpers like invalidateAllToolset(queryClient) to ensure all consumers refresh.

Telemetry & observability data fetching

Observability surfaces — Tool Logs, insights/analytics, summary cards, counts, and filter dropdowns — are served from pre-aggregated ClickHouse summary views behind endpoints like telemetry.getToolUsageSummary, telemetry.listToolUsageTraces, and telemetry.query. Default to these summary-backed endpoints; they're fast and are the right choice for almost every view.

Per-log detail is the rare exception. Free-text search over log bodies, arbitrary custom-attribute filters (e.g. @user.region), and inspecting an individual log/trace fall back to scanning the raw telemetry_logs table, which is slow. Only reach for those when detailed telemetry is genuinely what the user needs — not for default lists, summaries, or filter options.

When you add a control that triggers the raw-log path (a free-text search box, a custom-attribute filter), tell the user it may be slower — see SlowSearchNotice in LogsTools.tsx, shown only while such a filter is active — and keep the structured filters (server, user, agent, type, date) on the fast summary path. Don't build a default-on view whose first paint requires a raw-log scan.

Component Structure and Reuse

The core rule: every UI pattern that appears in more than two places must be centralized so it can be changed in a single location.

Check components/ before writing anything

Before writing any JSX for a UI element, check client/dashboard/src/components/ for an existing component. This includes layout wrappers, table headers, empty states, filter pill groups, search inputs, badges, cards — anything. Reuse what exists. Never create a one-off <div className="..."> when a named component already exists for that purpose.

If no component exists and you expect the pattern to appear in more than a few places across the app, create one in client/dashboard/src/components/ before using it. Name it for what it is, not where it happens to appear first (e.g., PageTabsTrigger, not SourceDetailTabTrigger).

No duplicated className strings

If the same Tailwind className string (or any meaningful substring of one) appears on 3+ elements anywhere in the codebase, extract it to:

• A component's built-in styling
• A cva variant
• A named const used in cn()

The symptom to watch for: copy-pasting a className prop. That is always wrong.

No duplicated JSX blocks

If you find yourself copy-pasting a JSX structure — even with minor variations — stop and extract a parameterized component. Three near-identical blocks is the threshold.

No IIFEs in JSX

Never use immediately-invoked function expressions inside JSX ({(() => { ... })()} ). Extract to a named sub-component or a variable above the return statement.

No multi-line or nested ternaries

A ternary that wraps onto multiple lines, or chains a second ?: inside a branch, is unreadable. Reach for one of these instead:

• A switch statement when mapping a discriminator (e.g. a kind / type string) to one of several values.
• A small named helper function, hoisted to module scope when the mapping is pure (e.g. converting a frontend enum to a backend constant). The helper labels the intent at the call site and the JSX stays flat.
• An object lookup when the keys are statically known and the values are simple constants.

// ❌ wrong — nested multi-line ternary
attachmentType={
  sourceKind === "function"
    ? "functions"
    : sourceKind === "externalmcp" || sourceKind === "remotemcp"
      ? "external_mcp"
      : "openapi"
}

// ✅ right — hoisted helper with a switch
function attachmentTypeForSourceKind(sourceKind: string | undefined): string {
  switch (sourceKind) {
    case "function":
      return "functions";
    case "externalmcp":
    case "remotemcp":
      return "external_mcp";
    default:
      return "openapi";
  }
}

attachmentType={attachmentTypeForSourceKind(sourceKind)}

Single-line, single-branch ternaries (isOpen ? "x" : "y") are fine.

Keep components focused

A component that has grown past ~150 lines of JSX is doing too much. Break it up. If a page has multiple tabs, each tab's content is its own component.

Page headers and subtext are a common duplication trap

Many pages render the same <h1> + <p> header block in 2–3 conditional render paths (loading skeleton, empty state, populated state). Examples observed: InsightsTools.tsx, LogsTools.tsx, LogsAgents.tsx, SecurityOverview.tsx, PolicyCenter.tsx. Symptoms: a copy change touches the same string in 3 places; Edit with replace_all fails because indentation differs between the duplicates.

When adding or editing page headers, lift the title and subtitle into a small <PageHeader title="…" subtitle="…" /> (or pass them as props to a shared shell), not into each render branch. When editing existing duplicated copy, target a unique trailing fragment of the string (e.g. "in chat messages.") so a single replace_all covers every copy regardless of indentation — and file a follow-up to extract a shared header.

Shared empty states: props with defaults, not forks

When the same empty-state component is reused across pages but needs different copy per caller (e.g. HooksEmptyState rendered from both /insights/tools and /logs/tools), add optional title / subtitle props with sensible defaults rather than forking the component:

export function HooksEmptyState({
  title = "No logs captured",
  subtitle = "Install Observability plugin in your AI agent to start capturing tool execution logs",
}: { title?: string; subtitle?: string } = {}) {
  /* … */
}

Backwards-compatible callers stay <HooksEmptyState />; only the variant caller passes overrides. Avoids divergent copies of the surrounding scaffolding (provider cards, setup dialogs, etc.).

Tables

Use the design system Table from @/components/ui/Table for dashboard tables. Do not add new shadcn table wrappers or hand-roll table styling with raw <table> markup when Table can express the UI. If you find a lingering legacy table pattern, migrate it when touched.

import { Column, Table } from "@/components/ui/Table";

For normal data tables, prefer the declarative columns / data / rowKey API. Define Column<T>[] near the component so render functions stay typed, use render for rich cells, and use width for stable layouts instead of ad hoc cell class widths.

const columns: Column<Role>[] = [
  {
    key: "name",
    header: "Name",
    width: "180px",
    render: (role) => <Type className="font-medium">{role.name}</Type>,
  },
  {
    key: "members",
    header: "Members",
    width: "100px",
    render: (role) => <Type>{role.memberCount}</Type>,
  },
];

<Table columns={columns} data={roles} rowKey={(row) => row.id} />;

For empty and loading states, use the Table's built-in empty surface and the shared SkeletonTable from @/components/ui/skeleton. Do not rebuild a one-off empty <tbody> or skeleton table.

<Table
  columns={columns}
  data={filteredKeys}
  rowKey={(row) => row.id}
  className="max-h-[500px] overflow-y-auto"
  noResultsMessage={<Type>No matching API keys</Type>}
/>

Search and filter controls are siblings above the table. On pages, wrap them in Page.Toolbar (see the page-toolbar skill); the bare Stack form below is for non-page surfaces like dialogs and sheets. Keep filter state outside the table, derive filtered rows with useMemo, and pass the result to data. Use existing controls such as SearchBar, MultiSelect, Select, or page-specific filter pills; do not put form controls inside Table.Header unless they are truly column headers. If the table is paginated, reset the page index when filters change.

const [search, setSearch] = useState("");
const [selectedTags, setSelectedTags] = useState<string[]>([]);

const filteredRows = useMemo(() => {
  const normalizedSearch = search.trim().toLowerCase();

  return rows.filter((row) => {
    const matchesSearch =
      normalizedSearch.length === 0 ||
      row.name.toLowerCase().includes(normalizedSearch);
    const matchesTags =
      selectedTags.length === 0 ||
      row.tags.some((tag) => selectedTags.includes(tag));

    return matchesSearch && matchesTags;
  });
}, [rows, search, selectedTags]);

<Stack direction="horizontal" gap={2} className="mb-4 h-fit">
  <SearchBar
    value={search}
    onChange={(value) => {
      setSearch(value);
      setPage(0);
    }}
    placeholder="Search tools"
    className="w-64"
  />
  <MultiSelect
    options={tagOptions}
    defaultValue={selectedTags}
    onValueChange={(value) => {
      setSelectedTags(value);
      setPage(0);
    }}
    placeholder="Filter by tag"
    autoSize
  />
</Stack>

<Table
  columns={columns}
  data={filteredRows}
  rowKey={(row) => row.id}
  noResultsMessage={<Type>No matching tools</Type>}
/>;

Footers that summarize, paginate, or load more rows should usually be sibling bars immediately below the table. The table API does not require a special footer component for this; keep the table declarative and put pagination/load-more controls after it.

<Table columns={columns} data={visibleRows} rowKey={(row) => row.id} />;

{
  totalPages > 1 && (
    <div className="flex items-center justify-between border-t px-4 py-3">
      <Type className="text-muted-foreground text-sm">
        {pageStart}-{pageEnd} of {filteredRows.length}
      </Type>
      <div className="flex items-center gap-1">
        <Button
          variant="tertiary"
          size="sm"
          onClick={() => setPage((page) => page - 1)}
          disabled={page === 0}
        >
          Previous
        </Button>
        <Button
          variant="tertiary"
          size="sm"
          onClick={() => setPage((page) => page + 1)}
          disabled={page >= totalPages - 1}
        >
          Next
        </Button>
      </div>
    </div>
  );
}

Use the compound API only when the body needs custom structure that the declarative API cannot express, such as mixed rows, a full-width CTA row, or a custom no-results branch. Keep the design system wrapper, header, row, and cell components as the default primitives.

<Table columns={columns}>
  <Table.Header columns={columns} />
  {items.length === 0 ? (
    <Table.NoResultsMessage>No results found.</Table.NoResultsMessage>
  ) : (
    <Table.Body>
      {items.map((item) => (
        <Table.Row key={item.id} row={item} columns={columns} />
      ))}
    </Table.Body>
  )}
  <Table.Row>
    <div className="border-border bg-muted/20 col-span-full border-t py-5 text-center">
      <Type className="text-muted-foreground text-sm">
        Want to grant new members access?
      </Type>
      <Button variant="tertiary" size="sm" className="mt-2">
        Configure Roles
      </Button>
    </div>
  </Table.Row>
</Table>

Use grouped or expandable rows through the table props instead of nesting unrelated cards or custom accordions around a table. Current patterns use hideHeader for grouped parent rows and renderExpandedContent for nested details.

<Table
  columns={groupColumns}
  data={groups}
  rowKey={(row) => row.key}
  hideHeader
  renderExpandedContent={(group) => (
    <Table
      columns={childColumns}
      data={group.items}
      rowKey={(row) => row.id}
      hideHeader
    />
  )}
/>

Raw <tr> / <td> should be rare and stay inside a <Table.Body> only when native table semantics are needed and Table does not expose them, such as a colSpan overflow row. If the row is a normal data row, use <Table.Row row={row} columns={columns} /> or the declarative data prop.

React Performance Patterns

These patterns were established in the audit log (#2140) and deployment log (#2167) redesigns. Apply them whenever building search, filtering, or keyboard navigation.

Hoist RegExp creation

Never create new RegExp() inside a render callback (e.g., highlightMatch). Extract it to a useMemo keyed on the search query:

const searchRegex = useMemo(() => {
  if (!searchQuery) return null;
  const escaped = searchQuery.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
  return new RegExp(`(${escaped})`, "gi");
}, [searchQuery]);

Then use searchRegex inside useCallback-wrapped functions.

Defer expensive search computations

Wrap search queries with useDeferredValue before passing them to expensive useMemo computations (e.g., filtering all logs). This keeps the input responsive while React defers the downstream recomputation:

const deferredSearchQuery = useDeferredValue(searchQuery);
const filteredIndices = useMemo(() => { /* expensive filter */ }, [deferredSearchQuery, ...]);

Derive state during render, not via useEffect

If a value can be computed from current state, derive it inline — don't sync it via useEffect. This prevents a flash of stale values between renders:

// DO: derive during render
const effectiveSearchIndex =
  searchMatchIndices.length > 0
    ? Math.min(currentSearchIndex, searchMatchIndices.length - 1)
    : 0;

// DON'T: clamp via useEffect (causes stale render flash)
useEffect(() => {
  if (currentSearchIndex >= searchMatchIndices.length) setCurrentSearchIndex(0);
}, [searchMatchIndices.length]);

Reset navigation state on data changes

When a component has keyboard navigation (j/k/g/G) with a currentIndex state, reset it when the underlying data changes (filters, pagination, data refresh):

useEffect(() => {
  setCurrentLogIndex(null);
}, [logs]); // or parsedLogs, depending on the component

Tooltip Usage

App.tsx wraps the entire app in a global TooltipProvider. Never add another TooltipProvider inside a component — doing so creates a redundant Radix context per instance and contributes to ResizeObserver loop completed with undelivered notifications errors in the browser.

Use <Tooltip>, <TooltipTrigger>, and <TooltipContent> directly — they inherit the global provider automatically. For simple cases use the existing <SimpleTooltip tooltip="..."> wrapper from @/components/ui/tooltip.

// ✅ correct
<Tooltip>
  <TooltipTrigger asChild>{button}</TooltipTrigger>
  <TooltipContent>Hello</TooltipContent>
</Tooltip>

// ❌ wrong — TooltipProvider already exists at the app root
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>{button}</TooltipTrigger>
    <TooltipContent>Hello</TooltipContent>
  </Tooltip>
</TooltipProvider>

Navigation and Links

Use the right primitive for the link type — mixing them causes full-page reloads, broken multi-tenancy, or missing security headers.

Internal navigation (any URL inside the dashboard): Use the route helpers from client/dashboard/src/routes.tsx. Top-level routes and subpages expose .Link, .href(), and .goTo():

// Wrap a child node with .Link
<routes.sources.Link>
  <Button>Connect a Source</Button>
</routes.sources.Link>

// Subpages get .Link too — use it instead of building strings
<routes.insights.tools.Link>
  <Button>Track AI usage</Button>
</routes.insights.tools.Link>

// Plain react-router Link with .href() when you need a className or are inside <p>
<Link to={routes.plugins.href()} className="underline underline-offset-2">
  Observability plugin
</Link>

Never hardcode org/project slugs in an href (e.g. https://app.getgram.ai/speakeasy-team/projects/default/plugins). The route helpers resolve the current :orgSlug / :projectSlug from the URL, so the same call works for every tenant.

External links (anywhere outside the dashboard): Use a plain <a> with target="_blank" and rel="noopener noreferrer". This matches the existing pattern (AddServerDialog.tsx:1162, CatalogDetail.tsx:229) and the security attributes are mandatory — noopener blocks window.opener access; noreferrer strips the Referer header.

<a
  href="https://www.speakeasy.com/product/mcp-gateway/catalog"
  target="_blank"
  rel="noopener noreferrer"
  className="underline underline-offset-2 hover:text-foreground"
>
  MCP Registry
</a>

The @/components/ui/link wrapper sets target="_blank" when external is true but also injects an icon — fine for nav rows, too heavy for inline links inside subtext. Reach for the plain <a> for inline external links.

Editing copy

• Always use American (US) English spelling in user-visible copy. Every string the user reads — labels, headings, buttons, tooltips, placeholders, empty states, toasts, error messages — uses American spelling, per the Speakeasy brand style guide. Highest-frequency cases: color not colour, canceled/canceling not cancelled/cancelling, behavior not behaviour, license (noun and verb) not licence, catalog not catalogue, gray not grey, center not centre, analyze not analyse, and -ize/-ization endings (organize, customize, authorization, synchronization) not -ise/-isation. This applies only to what the user reads — leave code identifiers, API field names, and third-party tokens alone even when they use British spelling (e.g. an upstream colour field stays colour; only the visible label is Americanized).
• Preserve dynamic tokens. Page subtext often interpolates state like {rangeLabel}, {periodUsage.credits}, or {projectName}. When rewording copy that contains a token, keep the token in place — replace it with the literal current value (e.g. "the last 30 days") only when the data fetch itself is locked to that value. Otherwise the copy starts lying as soon as the user changes a filter.
• Don't fight the Tailwind class sorter. Prettier's prettier-plugin-tailwindcss reorders classes on save. Write classes in any order; the formatter will normalize them and the diff stays clean across the codebase.
• AI context strings shadow user-visible names. When renaming a chart or card (e.g. "Most Used LLM Clients" → "Most Used Agents"), search for the old name in nearby contextInfo= / suggestions= props passed to ExploreWithAI / InsightsConfig. Those strings are sent to the LLM as analytical context; if they drift from the visible label, the AI assistant talks about a card the user can't see.