---

description: "Behavior-preserving React render-performance idioms"

globs: ["apps/sim/**/*.ts","apps/sim/**/*.tsx","packages/emcn/**","packages/workflow-renderer/**"]

---

<!-- Generated from .claude/rules/sim-react-performance.md by `bun run skills:sync`. Edit the source, not this file. -->

# React & Render Performance

Behavior-preserving performance idioms for components, hooks, and hot render paths. These are safe defaults — apply them freely. For the render-causing *effect/state* anti-patterns (derived state in effects, effect chains, state synced to a prop), use the dedicated skills: `/you-might-not-need-an-effect`, `/you-might-not-need-state`, `/you-might-not-need-a-memo`, `/you-might-not-need-a-callback`. Those refactors change render timing — verify them against the running UI, never mass-apply blind.

## Lazy-init refs that hold objects

`useRef(new Map())` / `useRef(new Set())` / `useRef({...})` allocates a fresh object on **every render** and throws it away — only the first is ever kept. Lazy-init instead so the allocation happens once.

```typescript

// ✗ Bad — allocates a new Map each render, discards all but the first

const cacheRef = useRef<Map<string, string>>(new Map())

// ✓ Good — allocated once, stable identity thereafter

const cacheRef = useRef<Map<string, string> | null>(null)

cacheRef.current ??= new Map()

```

Read `cacheRef.current` directly inside effects/handlers — refs are stable and never belong in a dependency array. A cheap primitive (`useRef(0)`, `useRef('')`, `useRef(null)`) needs no lazy init.

## Hoist static values and closure-free functions to module scope

A value or function declared inside a component is rebuilt every render. If it captures **nothing** from component scope (no props/state/refs), move it above the component at module scope. This skips the per-render allocation and keeps a stable identity so memoized children don't re-render.

```typescript

// ✗ Bad — rebuilt every render, new identity each time

function Toolbar({ mode }: ToolbarProps) {

const TITLES = { create: 'Add', edit: 'Configure' } as const

const handleWheel = (e: React.WheelEvent) => e.currentTarget.scrollBy(e.deltaX, e.deltaY)

// ...

}

// ✓ Good — allocated once at module load

const TITLES = { create: 'Add', edit: 'Configure' } as const

function handleWheel(e: React.WheelEvent) {

e.currentTarget.scrollBy(e.deltaX, e.deltaY)

}

function Toolbar({ mode }: ToolbarProps) { /* ... */ }

```

A closure-free function that IS wired through a ref sink or intentionally kept for stable identity may stay inline — hoisting a one-line `preventDefault` handler is churn, not a win. Hoist when it removes a real per-render allocation or unblocks child memoization.

## Pre-index with Map/Set for repeated lookups

`array.find()` / `array.includes()` / `array.indexOf()` scan the whole list each call. Inside a loop or a hot render path over a non-trivial list, that is O(n·m). Build a `Map` (for lookup-by-key) or `Set` (for membership) **once before** the loop, then look up in O(1).

```typescript

// ✗ Bad — find() re-scans outputs for every column

for (const child of columns) {

const output = group.outputs.find((o) => o.columnName === getColumnId(child))

}

// ✓ Good — index once, then O(1) lookups

const outputByName = new Map<string, Output>()

for (const o of group.outputs) {

if (!outputByName.has(o.columnName)) outputByName.set(o.columnName, o) // first wins, matches find()

}

for (const child of columns) {

const output = outputByName.get(getColumnId(child))

}

```

Preserve `.find()`'s **first-match** semantics when duplicate keys are possible: `new Map(arr.map(...))` keeps the *last* entry, so guard with `if (!map.has(key))` when replacing a `.find()`. Skip this for tiny, cold arrays (a handful of items in an event handler) where the Map build costs more than it saves.

## Never mutate a shared array in place

The real bug to avoid is `array.sort()` / `array.reverse()` on an array you don't own — sorting a React Query cache array in place corrupts shared state. Always sort a copy:

```typescript

// ✗ Bad — mutates the (possibly shared) source array in place

return items.sort(compare)

// ✓ Good — sorts a throwaway copy, source untouched

return [...items].sort(compare)

```

**Do NOT use `toSorted()` / `toReversed()` / `with()` / `toSpliced()`.** They are ES2023 *runtime* methods — and a tsconfig `"lib": ["ES2023"]` only makes them **type-check**, it does not make them **run**. Next/SWC compiles syntax but does **not** polyfill prototype methods, and the default browserslist still includes browsers without them (`toSorted` landed in Safari 16 / iOS 16, so any device capped at iOS 15 throws `TypeError: x.toSorted is not a function` and crashes the page). The perf difference vs `[...arr].sort()` is negligible (both allocate one array), so the copy-then-sort form is used everywhere: whether a module reaches the browser is not visible from its path. Every tsconfig keeps `"lib"` at or below ES2022 so `tsc` rejects these at each call site on a typed receiver (and still accepts OpenTelemetry's `context.with`, which it tells apart by type); `check:utils` fails if a tsconfig raises `lib` past ES2022, which is how they shipped in #5340, and also matches `toSorted`/`toReversed`/`toSpliced` in source, since tsc accepts any method on an `any` receiver. `.with` on an `any` receiver is caught by neither, so type a parsed array before copying from it. Never raise it to make one type-check.

## Run independent awaits in parallel

Sequential `await`s that don't consume each other's result serialize latency for nothing — in an async Server Component or a route handler this directly delays the response. Kick them off together with `Promise.all` and destructure.

```typescript

// ✗ Bad — waits for params, then separately waits for searchParams

const { id } = await params

const { kbName } = await searchParams

// ✓ Good — one combined wait

const [{ id }, { kbName }] = await Promise.all([params, searchParams])

```

Only keep awaits sequential when a later call genuinely uses an earlier result, or when the ordering is deliberate (rate-limited batches, retry loops, write-then-read).

## Carry exact lifecycle ownership across async boundaries

When asynchronous work can outlive an execution, session, or resource instance, capture its

opaque ownership token before the first `await` and pass that exact token through completion and

error cleanup. Never re-adopt the current owner from delayed cleanup: a replacement may now own

the same scope. End the lifecycle by exact-token match, and clear shared state only when that end

succeeds. Current-owner adoption is reserved for synchronous user actions that explicitly stop

the current lifecycle.

## Prefetch dynamic destination lists on intent

For long lists of dynamic destinations, do not viewport-prefetch every row and do not assume

`router.prefetch()` warms the full route: in Next 16 it uses the automatic/PPR strategy. Gate

`<Link prefetch={true}>` behind deliberate hover or keyboard focus, and prefetch destination

server state with the consumer's shared React Query options. A short, cancelable hover dwell

avoids drive-by downloads. Do not treat `touchstart` as intent because it also begins scrolling;

let the actual unmodified click start the data request.

A speculative failure must not poison a later visit when the app default disables

`retryOnMount`: remove only that exact failed query while it is inactive, keep failures visible

to mounted consumers, and set the shared options to `retryOnMount: true` so a quick-click failure

can recover after the user leaves and returns. Never carry placeholder data between protected

resource keys (for example, workspace A to workspace B); an explicit loading state is truthful.

If a continuity-focused surface intentionally omits `loading.tsx` so the current view remains

mounted until its peer is ready, the intent path must warm both the full route and its critical

data. Otherwise keep the loading boundary so dynamic navigation remains responsive.