AGENTS.md

profiles/vercel-labs/agent-skills/vercel-labs_agent-skills_react-best-practices/for-codex/AGENTS.md

AGENTS.md

Quality

72/100

Scores the file, not the repository.

Length

12,816 words

82 headings · 182 code blocks

Repository

— · pushed 9 days ago

Last changed

today

First indexed today.

nota-america/forgecat-agent-profiles/profiles/vercel-labs/agent-skills/vercel-labs_agent-skills_react-best-practices/for-codex/AGENTS.md

1

2# Sections

4This file defines all sections, their ordering, impact levels, and descriptions.

5The section ID (in parentheses) is the filename prefix used to group rules.

7---

9## 1. Eliminating Waterfalls (async)

11**Impact:** CRITICAL

12**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.

14## 2. Bundle Size Optimization (bundle)

16**Impact:** CRITICAL

17**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.

19## 3. Server-Side Performance (server)

21**Impact:** HIGH

22**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.

24## 4. Client-Side Data Fetching (client)

26**Impact:** MEDIUM-HIGH

27**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.

29## 5. Re-render Optimization (rerender)

31**Impact:** MEDIUM

32**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.

34## 6. Rendering Performance (rendering)

36**Impact:** MEDIUM

37**Description:** Optimizing the rendering process reduces the work the browser needs to do.

39## 7. JavaScript Performance (js)

41**Impact:** LOW-MEDIUM

42**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.

44## 8. Advanced Patterns (advanced)

46**Impact:** LOW

47**Description:** Advanced patterns for specific cases that require careful implementation.

48

50

51## Rule Title Here

53**Impact: MEDIUM (optional impact description)**

55Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.

57**Incorrect (description of what's wrong):**

59```typescript

60// Bad code example here

61const bad = example()

62```

64**Correct (description of what's right):**

66```typescript

67// Good code example here

68const good = example()

69```

71Reference: [Link to documentation or resource](https://example.com)

72

74

75## Do Not Put Effect Events in Dependency Arrays

77Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.

79**Incorrect (Effect Event added as a dependency):**

81```tsx

82import { useEffect, useEffectEvent } from 'react'

84function ChatRoom({ roomId, onConnected }: {

85 roomId: string

86 onConnected: () => void

87}) {

88 const handleConnected = useEffectEvent(onConnected)

90 useEffect(() => {

91 const connection = createConnection(roomId)

92 connection.on('connected', handleConnected)

93 connection.connect()

95 return () => connection.disconnect()

96 }, [roomId, handleConnected])

97}

98```

100Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.

101

102**Correct (depend on reactive values, not the Effect Event):**

103

104```tsx

105import { useEffect, useEffectEvent } from 'react'

106

107function ChatRoom({ roomId, onConnected }: {

108 roomId: string

109 onConnected: () => void

110}) {

111 const handleConnected = useEffectEvent(onConnected)

112

113 useEffect(() => {

114 const connection = createConnection(roomId)

115 connection.on('connected', handleConnected)

116 connection.connect()

117

118 return () => connection.disconnect()

119 }, [roomId])

120}

121```

122

123Reference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)

124

125

126

127## Store Event Handlers in Refs

128

129Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.

130

131**Incorrect (re-subscribes on every render):**

132

133```tsx

134function useWindowEvent(event: string, handler: (e) => void) {

135 useEffect(() => {

136 window.addEventListener(event, handler)

137 return () => window.removeEventListener(event, handler)

138 }, [event, handler])

139}

140```

141

142**Correct (stable subscription):**

143

144```tsx

145function useWindowEvent(event: string, handler: (e) => void) {

146 const handlerRef = useRef(handler)

147 useEffect(() => {

148 handlerRef.current = handler

149 }, [handler])

150

151 useEffect(() => {

152 const listener = (e) => handlerRef.current(e)

153 window.addEventListener(event, listener)

154 return () => window.removeEventListener(event, listener)

155 }, [event])

156}

157```

158

159**Alternative: use `useEffectEvent` if you're on latest React:**

160

161```tsx

162import { useEffectEvent } from 'react'

163

164function useWindowEvent(event: string, handler: (e) => void) {

165 const onEvent = useEffectEvent(handler)

166

167 useEffect(() => {

168 window.addEventListener(event, onEvent)

169 return () => window.removeEventListener(event, onEvent)

170 }, [event])

171}

172```

173

174`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

175

176

177

178## Initialize App Once, Not Per Mount

179

180Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.

181

182**Incorrect (runs twice in dev, re-runs on remount):**

183

184```tsx

185function Comp() {

186 useEffect(() => {

187 loadFromStorage()

188 checkAuthToken()

189 }, [])

190

191 // ...

192}

193```

194

195**Correct (once per app load):**

196

197```tsx

198let didInit = false

199

200function Comp() {

201 useEffect(() => {

202 if (didInit) return

203 didInit = true

204 loadFromStorage()

205 checkAuthToken()

206 }, [])

207

208 // ...

209}

210```

211

212Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)

213

214

215

216## useEffectEvent for Stable Callback Refs

217

218Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.

219

220**Incorrect (effect re-runs on every callback change):**

221

222```tsx

223function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {

224 const [query, setQuery] = useState('')

225

226 useEffect(() => {

227 const timeout = setTimeout(() => onSearch(query), 300)

228 return () => clearTimeout(timeout)

229 }, [query, onSearch])

230}

231```

232

233**Correct (using React's useEffectEvent):**

234

235```tsx

236import { useEffectEvent } from 'react';

237

238function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {

239 const [query, setQuery] = useState('')

240 const onSearchEvent = useEffectEvent(onSearch)

241

242 useEffect(() => {

243 const timeout = setTimeout(() => onSearchEvent(query), 300)

244 return () => clearTimeout(timeout)

245 }, [query])

246}

247```

248

249

250

251## Prevent Waterfall Chains in API Routes

252

253In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.

254

255**Incorrect (config waits for auth, data waits for both):**

256

257```typescript

258export async function GET(request: Request) {

259 const session = await auth()

260 const config = await fetchConfig()

261 const data = await fetchData(session.user.id)

262 return Response.json({ data, config })

263}

264```

265

266**Correct (auth and config start immediately):**

267

268```typescript

269export async function GET(request: Request) {

270 const sessionPromise = auth()

271 const configPromise = fetchConfig()

272 const session = await sessionPromise

273 const [config, data] = await Promise.all([

274 configPromise,

275 fetchData(session.user.id)

276 ])

277 return Response.json({ data, config })

278}

279```

280

281For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

282

283

284

285## Check Cheap Conditions Before Async Flags

286

287When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.

288

289This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.

290

291**Incorrect:**

292

293```typescript

294const someFlag = await getFlag()

295

296if (someFlag && someCondition) {

297 // ...

298}

299```

300

301**Correct:**

302

303```typescript

304if (someCondition) {

305 const someFlag = await getFlag()

306 if (someFlag) {

307 // ...

308 }

309}

310```

311

312This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.

313

314Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.

315

316

317

318## Defer Await Until Needed

319

320Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.

321

322**Incorrect (blocks both branches):**

323

324```typescript

325async function handleRequest(userId: string, skipProcessing: boolean) {

326 const userData = await fetchUserData(userId)

327

328 if (skipProcessing) {

329 // Returns immediately but still waited for userData

330 return { skipped: true }

331 }

332

333 // Only this branch uses userData

334 return processUserData(userData)

335}

336```

337

338**Correct (only blocks when needed):**

339

340```typescript

341async function handleRequest(userId: string, skipProcessing: boolean) {

342 if (skipProcessing) {

343 // Returns immediately without waiting

344 return { skipped: true }

345 }

346

347 // Fetch only when needed

348 const userData = await fetchUserData(userId)

349 return processUserData(userData)

350}

351```

352

353**Another example (early return optimization):**

354

355```typescript

356// Incorrect: always fetches permissions

357async function updateResource(resourceId: string, userId: string) {

358 const permissions = await fetchPermissions(userId)

359 const resource = await getResource(resourceId)

360

361 if (!resource) {

362 return { error: 'Not found' }

363 }

364

365 if (!permissions.canEdit) {

366 return { error: 'Forbidden' }

367 }

368

369 return await updateResourceData(resource, permissions)

370}

371

372// Correct: fetches only when needed

373async function updateResource(resourceId: string, userId: string) {

374 const resource = await getResource(resourceId)

375

376 if (!resource) {

377 return { error: 'Not found' }

378 }

379

380 const permissions = await fetchPermissions(userId)

381

382 if (!permissions.canEdit) {

383 return { error: 'Forbidden' }

384 }

385

386 return await updateResourceData(resource, permissions)

387}

388```

389

390This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.

391

392For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).

393

394

395

396## Dependency-Based Parallelization

397

398For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.

399

400**Incorrect (profile waits for config unnecessarily):**

401

402```typescript

403const [user, config] = await Promise.all([

404 fetchUser(),

405 fetchConfig()

406])

407const profile = await fetchProfile(user.id)

408```

409

410**Correct (config and profile run in parallel):**

411

412```typescript

413import { all } from 'better-all'

414

415const { user, config, profile } = await all({

416 async user() { return fetchUser() },

417 async config() { return fetchConfig() },

418 async profile() {

419 return fetchProfile((await this.$.user).id)

420 }

421})

422```

423

424**Alternative without extra dependencies:**

425

426We can also create all the promises first, and do `Promise.all()` at the end.

427

428```typescript

429const userPromise = fetchUser()

430const profilePromise = userPromise.then(user => fetchProfile(user.id))

431

432const [user, config, profile] = await Promise.all([

433 userPromise,

434 fetchConfig(),

435 profilePromise

436])

437```

438

439Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

440

441

442

443## Promise.all() for Independent Operations

444

445When async operations have no interdependencies, execute them concurrently using `Promise.all()`.

446

447**Incorrect (sequential execution, 3 round trips):**

448

449```typescript

450const user = await fetchUser()

451const posts = await fetchPosts()

452const comments = await fetchComments()

453```

454

455**Correct (parallel execution, 1 round trip):**

456

457```typescript

458const [user, posts, comments] = await Promise.all([

459 fetchUser(),

460 fetchPosts(),

461 fetchComments()

462])

463```

464

465

466

467## Strategic Suspense Boundaries

468

469Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.

470

471**Incorrect (wrapper blocked by data fetching):**

472

473```tsx

474async function Page() {

475 const data = await fetchData() // Blocks entire page

476

477 return (

478 <div>

479 <div>Sidebar</div>

480 <div>Header</div>

481 <div>

482 <DataDisplay data={data} />

483 </div>

484 <div>Footer</div>

485 </div>

486 )

487}

488```

489

490The entire layout waits for data even though only the middle section needs it.

491

492**Correct (wrapper shows immediately, data streams in):**

493

494```tsx

495function Page() {

496 return (

497 <div>

498 <div>Sidebar</div>

499 <div>Header</div>

500 <div>

501 <Suspense fallback={<Skeleton />}>

502 <DataDisplay />

503 </Suspense>

504 </div>

505 <div>Footer</div>

506 </div>

507 )

508}

509

510async function DataDisplay() {

511 const data = await fetchData() // Only blocks this component

512 return <div>{data.content}</div>

513}

514```

515

516Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.

517

518**Alternative (share promise across components):**

519

520```tsx

521function Page() {

522 // Start fetch immediately, but don't await

523 const dataPromise = fetchData()

524

525 return (

526 <div>

527 <div>Sidebar</div>

528 <div>Header</div>

529 <Suspense fallback={<Skeleton />}>

530 <DataDisplay dataPromise={dataPromise} />

531 <DataSummary dataPromise={dataPromise} />

532 </Suspense>

533 <div>Footer</div>

534 </div>

535 )

536}

537

538function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {

539 const data = use(dataPromise) // Unwraps the promise

540 return <div>{data.content}</div>

541}

542

543function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {

544 const data = use(dataPromise) // Reuses the same promise

545 return <div>{data.summary}</div>

546}

547```

548

549Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.

550

551**When NOT to use this pattern:**

552

553- Critical data needed for layout decisions (affects positioning)

554- SEO-critical content above the fold

555- Small, fast queries where suspense overhead isn't worth it

556- When you want to avoid layout shift (loading → content jump)

557

558**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.

559

560

561

562## Prefer Statically Analyzable Paths

563

564Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.

565

566Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.

567

568When analysis becomes too broad, the cost is real:

569- Larger server bundles

570- Slower builds

571- Worse cold starts

572- More memory use

573

574### Import Paths

575

576**Incorrect (the bundler cannot tell what may be imported):**

577

578```ts

579const PAGE_MODULES = {

580 home: './pages/home',

581 settings: './pages/settings',

582} as const

583

584const Page = await import(PAGE_MODULES[pageName])

585```

586

587**Correct (use an explicit map of allowed modules):**

588

589```ts

590const PAGE_MODULES = {

591 home: () => import('./pages/home'),

592 settings: () => import('./pages/settings'),

593} as const

594

595const Page = await PAGE_MODULES[pageName]()

596```

597

598### File-System Paths

599

600**Incorrect (a 2-value enum still hides the final path from static analysis):**

601

602```ts

603const baseDir = path.join(process.cwd(), 'content/' + contentKind)

604```

605

606**Correct (make each final path literal at the callsite):**

607

608```ts

609const baseDir =

610 kind === ContentKind.Blog

611 ? path.join(process.cwd(), 'content/blog')

612 : path.join(process.cwd(), 'content/docs')

613```

614

615In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.

616

617Reference: [Next.js output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [Next.js dynamic imports](https://nextjs.org/learn/seo/dynamic-imports), [Vite features](https://vite.dev/guide/features.html), [esbuild API](https://esbuild.github.io/api/), [Rollup dynamic import vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [Webpack dependency management](https://webpack.js.org/guides/dependency-management/)

618

619

620

621## Avoid Barrel File Imports

622

623Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).

624

625Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.

626

627**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.

628

629**Incorrect (imports entire library):**

630

631```tsx

632import { Check, X, Menu } from 'lucide-react'

633// Loads 1,583 modules, takes ~2.8s extra in dev

634// Runtime cost: 200-800ms on every cold start

635

636import { Button, TextField } from '@mui/material'

637// Loads 2,225 modules, takes ~4.2s extra in dev

638```

639

640**Correct - Next.js 13.5+ (recommended):**

641

642```js

643// next.config.js - automatically optimizes barrel imports at build time

644module.exports = {

645 experimental: {

646 optimizePackageImports: ['lucide-react', '@mui/material']

647 }

648}

649```

650

651```tsx

652// Keep the standard imports - Next.js transforms them to direct imports

653import { Check, X, Menu } from 'lucide-react'

654// Full TypeScript support, no manual path wrangling

655```

656

657This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.

658

659**Correct - Direct imports (non-Next.js projects):**

660

661```tsx

662import Button from '@mui/material/Button'

663import TextField from '@mui/material/TextField'

664// Loads only what you use

665```

666

667> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.

668

669These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.

670

671Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.

672

673Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)

674

675

676

677## Conditional Module Loading

678

679Load large data or modules only when a feature is activated.

680

681**Example (lazy-load animation frames):**

682

683```tsx

684function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {

685 const [frames, setFrames] = useState<Frame[] | null>(null)

686

687 useEffect(() => {

688 if (enabled && !frames && typeof window !== 'undefined') {

689 import('./animation-frames.js')

690 .then(mod => setFrames(mod.frames))

691 .catch(() => setEnabled(false))

692 }

693 }, [enabled, frames, setEnabled])

694

695 if (!frames) return <Skeleton />

696 return <Canvas frames={frames} />

697}

698```

699

700The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.

701

702

703

704## Defer Non-Critical Third-Party Libraries

705

706Analytics, logging, and error tracking don't block user interaction. Load them after hydration.

707

708**Incorrect (blocks initial bundle):**

709

710```tsx

711import { Analytics } from '@vercel/analytics/react'

712

713export default function RootLayout({ children }) {

714 return (

715 <html>

716 <body>

717 {children}

718 <Analytics />

719 </body>

720 </html>

721 )

722}

723```

724

725**Correct (loads after hydration):**

726

727```tsx

728import dynamic from 'next/dynamic'

729

730const Analytics = dynamic(

731 () => import('@vercel/analytics/react').then(m => m.Analytics),

732 { ssr: false }

733)

734

735export default function RootLayout({ children }) {

736 return (

737 <html>

738 <body>

739 {children}

740 <Analytics />

741 </body>

742 </html>

743 )

744}

745```

746

747

748

749## Dynamic Imports for Heavy Components

750

751Use `next/dynamic` to lazy-load large components not needed on initial render.

752

753**Incorrect (Monaco bundles with main chunk ~300KB):**

754

755```tsx

756import { MonacoEditor } from './monaco-editor'

757

758function CodePanel({ code }: { code: string }) {

759 return <MonacoEditor value={code} />

760}

761```

762

763**Correct (Monaco loads on demand):**

764

765```tsx

766import dynamic from 'next/dynamic'

767

768const MonacoEditor = dynamic(

769 () => import('./monaco-editor').then(m => m.MonacoEditor),

770 { ssr: false }

771)

772

773function CodePanel({ code }: { code: string }) {

774 return <MonacoEditor value={code} />

775}

776```

777

778

779

780## Preload Based on User Intent

781

782Preload heavy bundles before they're needed to reduce perceived latency.

783

784**Example (preload on hover/focus):**

785

786```tsx

787function EditorButton({ onClick }: { onClick: () => void }) {

788 const preload = () => {

789 if (typeof window !== 'undefined') {

790 void import('./monaco-editor')

791 }

792 }

793

794 return (

795 <button

796 onMouseEnter={preload}

797 onFocus={preload}

798 onClick={onClick}

799 >

800 Open Editor

801 </button>

802 )

803}

804```

805

806**Example (preload when feature flag is enabled):**

807

808```tsx

809function FlagsProvider({ children, flags }: Props) {

810 useEffect(() => {

811 if (flags.editorEnabled && typeof window !== 'undefined') {

812 void import('./monaco-editor').then(mod => mod.init())

813 }

814 }, [flags.editorEnabled])

815

816 return <FlagsContext.Provider value={flags}>

817 {children}

818 </FlagsContext.Provider>

819}

820```

821

822The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.

823

824

825

826## Deduplicate Global Event Listeners

827

828Use `useSWRSubscription()` to share global event listeners across component instances.

829

830**Incorrect (N instances = N listeners):**

831

832```tsx

833function useKeyboardShortcut(key: string, callback: () => void) {

834 useEffect(() => {

835 const handler = (e: KeyboardEvent) => {

836 if (e.metaKey && e.key === key) {

837 callback()

838 }

839 }

840 window.addEventListener('keydown', handler)

841 return () => window.removeEventListener('keydown', handler)

842 }, [key, callback])

843}

844```

845

846When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.

847

848**Correct (N instances = 1 listener):**

849

850```tsx

851import useSWRSubscription from 'swr/subscription'

852

853// Module-level Map to track callbacks per key

854const keyCallbacks = new Map<string, Set<() => void>>()

855

856function useKeyboardShortcut(key: string, callback: () => void) {

857 // Register this callback in the Map

858 useEffect(() => {

859 if (!keyCallbacks.has(key)) {

860 keyCallbacks.set(key, new Set())

861 }

862 keyCallbacks.get(key)!.add(callback)

863

864 return () => {

865 const set = keyCallbacks.get(key)

866 if (set) {

867 set.delete(callback)

868 if (set.size === 0) {

869 keyCallbacks.delete(key)

870 }

871 }

872 }

873 }, [key, callback])

874

875 useSWRSubscription('global-keydown', () => {

876 const handler = (e: KeyboardEvent) => {

877 if (e.metaKey && keyCallbacks.has(e.key)) {

878 keyCallbacks.get(e.key)!.forEach(cb => cb())

879 }

880 }

881 window.addEventListener('keydown', handler)

882 return () => window.removeEventListener('keydown', handler)

883 })

884}

885

886function Profile() {

887 // Multiple shortcuts will share the same listener

888 useKeyboardShortcut('p', () => { /* ... */ })

889 useKeyboardShortcut('k', () => { /* ... */ })

890 // ...

891}

892```

893

894

895

896## Version and Minimize localStorage Data

897

898Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.

899

900**Incorrect:**

901

902```typescript

903// No version, stores everything, no error handling

904localStorage.setItem('userConfig', JSON.stringify(fullUserObject))

905const data = localStorage.getItem('userConfig')

906```

907

908**Correct:**

909

910```typescript

911const VERSION = 'v2'

912

913function saveConfig(config: { theme: string; language: string }) {

914 try {

915 localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))

916 } catch {

917 // Throws in incognito/private browsing, quota exceeded, or disabled

918 }

919}

920

921function loadConfig() {

922 try {

923 const data = localStorage.getItem(`userConfig:${VERSION}`)

924 return data ? JSON.parse(data) : null

925 } catch {

926 return null

927 }

928}

929

930// Migration from v1 to v2

931function migrate() {

932 try {

933 const v1 = localStorage.getItem('userConfig:v1')

934 if (v1) {

935 const old = JSON.parse(v1)

936 saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })

937 localStorage.removeItem('userConfig:v1')

938 }

939 } catch {}

940}

941```

942

943**Store minimal fields from server responses:**

944

945```typescript

946// User object has 20+ fields, only store what UI needs

947function cachePrefs(user: FullUser) {

948 try {

949 localStorage.setItem('prefs:v1', JSON.stringify({

950 theme: user.preferences.theme,

951 notifications: user.preferences.notifications

952 }))

953 } catch {}

954}

955```

956

957**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.

958

959**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.

960

961

962

963## Use Passive Event Listeners for Scrolling Performance

964

965Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.

966

967**Incorrect:**

968

969```typescript

970useEffect(() => {

971 const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)

972 const handleWheel = (e: WheelEvent) => console.log(e.deltaY)

973

974 document.addEventListener('touchstart', handleTouch)

975 document.addEventListener('wheel', handleWheel)

976

977 return () => {

978 document.removeEventListener('touchstart', handleTouch)

979 document.removeEventListener('wheel', handleWheel)

980 }

981}, [])

982```

983

984**Correct:**

985

986```typescript

987useEffect(() => {

988 const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)

989 const handleWheel = (e: WheelEvent) => console.log(e.deltaY)

990

991 document.addEventListener('touchstart', handleTouch, { passive: true })

992 document.addEventListener('wheel', handleWheel, { passive: true })

993

994 return () => {

995 document.removeEventListener('touchstart', handleTouch)

996 document.removeEventListener('wheel', handleWheel)

997 }

998}, [])

999```

1000

1001**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.

1002

1003**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.

1004

1005

1006

1007## Use SWR for Automatic Deduplication

1008

1009SWR enables request deduplication, caching, and revalidation across component instances.

1010

1011**Incorrect (no deduplication, each instance fetches):**

1012

1013```tsx

1014function UserList() {

1015 const [users, setUsers] = useState([])

1016 useEffect(() => {

1017 fetch('/api/users')

1018 .then(r => r.json())

1019 .then(setUsers)

1020 }, [])

1021}

1022```

1023

1024**Correct (multiple instances share one request):**

1025

1026```tsx

1027import useSWR from 'swr'

1028

1029function UserList() {

1030 const { data: users } = useSWR('/api/users', fetcher)

1031}

1032```

1033

1034**For immutable data:**

1035

1036```tsx

1037import { useImmutableSWR } from '@/lib/swr'

1038

1039function StaticContent() {

1040 const { data } = useImmutableSWR('/api/config', fetcher)

1041}

1042```

1043

1044**For mutations:**

1045

1046```tsx

1047import { useSWRMutation } from 'swr/mutation'

1048

1049function UpdateButton() {

1050 const { trigger } = useSWRMutation('/api/user', updateUser)

1051 return <button onClick={() => trigger()}>Update</button>

1052}

1053```

1054

1055Reference: [https://swr.vercel.app](https://swr.vercel.app)

1056

1057

1058

1059## Avoid Layout Thrashing

1060

1061Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.

1062

1063**This is OK (browser batches style changes):**

1064```typescript

1065function updateElementStyles(element: HTMLElement) {

1066 // Each line invalidates style, but browser batches the recalculation

1067 element.style.width = '100px'

1068 element.style.height = '200px'

1069 element.style.backgroundColor = 'blue'

1070 element.style.border = '1px solid black'

1071}

1072```

1073

1074**Incorrect (interleaved reads and writes force reflows):**

1075```typescript

1076function layoutThrashing(element: HTMLElement) {

1077 element.style.width = '100px'

1078 const width = element.offsetWidth // Forces reflow

1079 element.style.height = '200px'

1080 const height = element.offsetHeight // Forces another reflow

1081}

1082```

1083

1084**Correct (batch writes, then read once):**

1085```typescript

1086function updateElementStyles(element: HTMLElement) {

1087 // Batch all writes together

1088 element.style.width = '100px'

1089 element.style.height = '200px'

1090 element.style.backgroundColor = 'blue'

1091 element.style.border = '1px solid black'

1092

1093 // Read after all writes are done (single reflow)

1094 const { width, height } = element.getBoundingClientRect()

1095}

1096```

1097

1098**Correct (batch reads, then writes):**

1099```typescript

1100function avoidThrashing(element: HTMLElement) {

1101 // Read phase - all layout queries first

1102 const rect1 = element.getBoundingClientRect()

1103 const offsetWidth = element.offsetWidth

1104 const offsetHeight = element.offsetHeight

1105

1106 // Write phase - all style changes after

1107 element.style.width = '100px'

1108 element.style.height = '200px'

1109}

1110```

1111

1112**Better: use CSS classes**

1113```css

1114.highlighted-box {

1115 width: 100px;

1116 height: 200px;

1117 background-color: blue;

1118 border: 1px solid black;

1119}

1120```

1121```typescript

1122function updateElementStyles(element: HTMLElement) {

1123 element.classList.add('highlighted-box')

1124

1125 const { width, height } = element.getBoundingClientRect()

1126}

1127```

1128

1129**React example:**

1130```tsx

1131// Incorrect: interleaving style changes with layout queries

1132function Box({ isHighlighted }: { isHighlighted: boolean }) {

1133 const ref = useRef<HTMLDivElement>(null)

1134

1135 useEffect(() => {

1136 if (ref.current && isHighlighted) {

1137 ref.current.style.width = '100px'

1138 const width = ref.current.offsetWidth // Forces layout

1139 ref.current.style.height = '200px'

1140 }

1141 }, [isHighlighted])

1142

1143 return <div ref={ref}>Content</div>

1144}

1145

1146// Correct: toggle class

1147function Box({ isHighlighted }: { isHighlighted: boolean }) {

1148 return (

1149 <div className={isHighlighted ? 'highlighted-box' : ''}>

1150 Content

1151 </div>

1152 )

1153}

1154```

1155

1156Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.

1157

1158See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.

1159

1160

1161

1162## Cache Repeated Function Calls

1163

1164Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.

1165

1166**Incorrect (redundant computation):**

1167

1168```typescript

1169function ProjectList({ projects }: { projects: Project[] }) {

1170 return (

1171 <div>

1172 {projects.map(project => {

1173 // slugify() called 100+ times for same project names

1174 const slug = slugify(project.name)

1175

1176 return <ProjectCard key={project.id} slug={slug} />

1177 })}

1178 </div>

1179 )

1180}

1181```

1182

1183**Correct (cached results):**

1184

1185```typescript

1186// Module-level cache

1187const slugifyCache = new Map<string, string>()

1188

1189function cachedSlugify(text: string): string {

1190 if (slugifyCache.has(text)) {

1191 return slugifyCache.get(text)!

1192 }

1193 const result = slugify(text)

1194 slugifyCache.set(text, result)

1195 return result

1196}

1197

1198function ProjectList({ projects }: { projects: Project[] }) {

1199 return (

1200 <div>

1201 {projects.map(project => {

1202 // Computed only once per unique project name

1203 const slug = cachedSlugify(project.name)

1204

1205 return <ProjectCard key={project.id} slug={slug} />

1206 })}

1207 </div>

1208 )

1209}

1210```

1211

1212**Simpler pattern for single-value functions:**

1213

1214```typescript

1215let isLoggedInCache: boolean | null = null

1216

1217function isLoggedIn(): boolean {

1218 if (isLoggedInCache !== null) {

1219 return isLoggedInCache

1220 }

1221

1222 isLoggedInCache = document.cookie.includes('auth=')

1223 return isLoggedInCache

1224}

1225

1226// Clear cache when auth changes

1227function onAuthChange() {

1228 isLoggedInCache = null

1229}

1230```

1231

1232Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.

1233

1234Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

1235

1236

1237

1238## Cache Property Access in Loops

1239

1240Cache object property lookups in hot paths.

1241

1242**Incorrect (3 lookups × N iterations):**

1243

1244```typescript

1245for (let i = 0; i < arr.length; i++) {

1246 process(obj.config.settings.value)

1247}

1248```

1249

1250**Correct (1 lookup total):**

1251

1252```typescript

1253const value = obj.config.settings.value

1254const len = arr.length

1255for (let i = 0; i < len; i++) {

1256 process(value)

1257}

1258```

1259

1260

1261

1262## Cache Storage API Calls

1263

1264`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.

1265

1266**Incorrect (reads storage on every call):**

1267

1268```typescript

1269function getTheme() {

1270 return localStorage.getItem('theme') ?? 'light'

1271}

1272// Called 10 times = 10 storage reads

1273```

1274

1275**Correct (Map cache):**

1276

1277```typescript

1278const storageCache = new Map<string, string | null>()

1279

1280function getLocalStorage(key: string) {

1281 if (!storageCache.has(key)) {

1282 storageCache.set(key, localStorage.getItem(key))

1283 }

1284 return storageCache.get(key)

1285}

1286

1287function setLocalStorage(key: string, value: string) {

1288 localStorage.setItem(key, value)

1289 storageCache.set(key, value) // keep cache in sync

1290}

1291```

1292

1293Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.

1294

1295**Cookie caching:**

1296

1297```typescript

1298let cookieCache: Record<string, string> | null = null

1299

1300function getCookie(name: string) {

1301 if (!cookieCache) {

1302 cookieCache = Object.fromEntries(

1303 document.cookie.split('; ').map(c => c.split('='))

1304 )

1305 }

1306 return cookieCache[name]

1307}

1308```

1309

1310**Important (invalidate on external changes):**

1311

1312If storage can change externally (another tab, server-set cookies), invalidate cache:

1313

1314```typescript

1315window.addEventListener('storage', (e) => {

1316 if (e.key) storageCache.delete(e.key)

1317})

1318

1319document.addEventListener('visibilitychange', () => {

1320 if (document.visibilityState === 'visible') {

1321 storageCache.clear()

1322 }

1323})

1324```

1325

1326

1327

1328## Combine Multiple Array Iterations

1329

1330Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.

1331

1332**Incorrect (3 iterations):**

1333

1334```typescript

1335const admins = users.filter(u => u.isAdmin)

1336const testers = users.filter(u => u.isTester)

1337const inactive = users.filter(u => !u.isActive)

1338```

1339

1340**Correct (1 iteration):**

1341

1342```typescript

1343const admins: User[] = []

1344const testers: User[] = []

1345const inactive: User[] = []

1346

1347for (const user of users) {

1348 if (user.isAdmin) admins.push(user)

1349 if (user.isTester) testers.push(user)

1350 if (!user.isActive) inactive.push(user)

1351}

1352```

1353

1354

1355

1356## Early Return from Functions

1357

1358Return early when result is determined to skip unnecessary processing.

1359

1360**Incorrect (processes all items even after finding answer):**

1361

1362```typescript

1363function validateUsers(users: User[]) {

1364 let hasError = false

1365 let errorMessage = ''

1366

1367 for (const user of users) {

1368 if (!user.email) {

1369 hasError = true

1370 errorMessage = 'Email required'

1371 }

1372 if (!user.name) {

1373 hasError = true

1374 errorMessage = 'Name required'

1375 }

1376 // Continues checking all users even after error found

1377 }

1378

1379 return hasError ? { valid: false, error: errorMessage } : { valid: true }

1380}

1381```

1382

1383**Correct (returns immediately on first error):**

1384

1385```typescript

1386function validateUsers(users: User[]) {

1387 for (const user of users) {

1388 if (!user.email) {

1389 return { valid: false, error: 'Email required' }

1390 }

1391 if (!user.name) {

1392 return { valid: false, error: 'Name required' }

1393 }

1394 }

1395

1396 return { valid: true }

1397}

1398```

1399

1400

1401

1402## Use flatMap to Map and Filter in One Pass

1403

1404**Impact: LOW-MEDIUM (eliminates intermediate array)**

1405

1406Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.

1407

1408**Incorrect (2 iterations, intermediate array):**

1409

1410```typescript

1411const userNames = users

1412 .map(user => user.isActive ? user.name : null)

1413 .filter(Boolean)

1414```

1415

1416**Correct (1 iteration, no intermediate array):**

1417

1418```typescript

1419const userNames = users.flatMap(user =>

1420 user.isActive ? [user.name] : []

1421)

1422```

1423

1424**More examples:**

1425

1426```typescript

1427// Extract valid emails from responses

1428// Before

1429const emails = responses

1430 .map(r => r.success ? r.data.email : null)

1431 .filter(Boolean)

1432

1433// After

1434const emails = responses.flatMap(r =>

1435 r.success ? [r.data.email] : []

1436)

1437

1438// Parse and filter valid numbers

1439// Before

1440const numbers = strings

1441 .map(s => parseInt(s, 10))

1442 .filter(n => !isNaN(n))

1443

1444// After

1445const numbers = strings.flatMap(s => {

1446 const n = parseInt(s, 10)

1447 return isNaN(n) ? [] : [n]

1448})

1449```

1450

1451**When to use:**

1452- Transforming items while filtering some out

1453- Conditional mapping where some inputs produce no output

1454- Parsing/validating where invalid inputs should be skipped

1455

1456

1457

1458## Hoist RegExp Creation

1459

1460Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.

1461

1462**Incorrect (new RegExp every render):**

1463

1464```tsx

1465function Highlighter({ text, query }: Props) {

1466 const regex = new RegExp(`(${query})`, 'gi')

1467 const parts = text.split(regex)

1468 return <>{parts.map((part, i) => ...)}</>

1469}

1470```

1471

1472**Correct (memoize or hoist):**

1473

1474```tsx

1475const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

1476

1477function Highlighter({ text, query }: Props) {

1478 const regex = useMemo(

1479 () => new RegExp(`(${escapeRegex(query)})`, 'gi'),

1480 [query]

1481 )

1482 const parts = text.split(regex)

1483 return <>{parts.map((part, i) => ...)}</>

1484}

1485```

1486

1487**Warning (global regex has mutable state):**

1488

1489Global regex (`/g`) has mutable `lastIndex` state:

1490

1491```typescript

1492const regex = /foo/g

1493regex.test('foo') // true, lastIndex = 3

1494regex.test('foo') // false, lastIndex = 0

1495```

1496

1497

1498

1499## Build Index Maps for Repeated Lookups

1500

1501Multiple `.find()` calls by the same key should use a Map.

1502

1503**Incorrect (O(n) per lookup):**

1504

1505```typescript

1506function processOrders(orders: Order[], users: User[]) {

1507 return orders.map(order => ({

1508 ...order,

1509 user: users.find(u => u.id === order.userId)

1510 }))

1511}

1512```

1513

1514**Correct (O(1) per lookup):**

1515

1516```typescript

1517function processOrders(orders: Order[], users: User[]) {

1518 const userById = new Map(users.map(u => [u.id, u]))

1519

1520 return orders.map(order => ({

1521 ...order,

1522 user: userById.get(order.userId)

1523 }))

1524}

1525```

1526

1527Build map once (O(n)), then all lookups are O(1).

1528For 1000 orders × 1000 users: 1M ops → 2K ops.

1529

1530

1531

1532## Early Length Check for Array Comparisons

1533

1534When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.

1535

1536In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).

1537

1538**Incorrect (always runs expensive comparison):**

1539

1540```typescript

1541function hasChanges(current: string[], original: string[]) {

1542 // Always sorts and joins, even when lengths differ

1543 return current.sort().join() !== original.sort().join()

1544}

1545```

1546

1547Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.

1548

1549**Correct (O(1) length check first):**

1550

1551```typescript

1552function hasChanges(current: string[], original: string[]) {

1553 // Early return if lengths differ

1554 if (current.length !== original.length) {

1555 return true

1556 }

1557 // Only sort when lengths match

1558 const currentSorted = current.toSorted()

1559 const originalSorted = original.toSorted()

1560 for (let i = 0; i < currentSorted.length; i++) {

1561 if (currentSorted[i] !== originalSorted[i]) {

1562 return true

1563 }

1564 }

1565 return false

1566}

1567```

1568

1569This new approach is more efficient because:

1570- It avoids the overhead of sorting and joining the arrays when lengths differ

1571- It avoids consuming memory for the joined strings (especially important for large arrays)

1572- It avoids mutating the original arrays

1573- It returns early when a difference is found

1574

1575

1576

1577## Use Loop for Min/Max Instead of Sort

1578

1579Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.

1580

1581**Incorrect (O(n log n) - sort to find latest):**

1582

1583```typescript

1584interface Project {

1585 id: string

1586 name: string

1587 updatedAt: number

1588}

1589

1590function getLatestProject(projects: Project[]) {

1591 const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)

1592 return sorted[0]

1593}

1594```

1595

1596Sorts the entire array just to find the maximum value.

1597

1598**Incorrect (O(n log n) - sort for oldest and newest):**

1599

1600```typescript

1601function getOldestAndNewest(projects: Project[]) {

1602 const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)

1603 return { oldest: sorted[0], newest: sorted[sorted.length - 1] }

1604}

1605```

1606

1607Still sorts unnecessarily when only min/max are needed.

1608

1609**Correct (O(n) - single loop):**

1610

1611```typescript

1612function getLatestProject(projects: Project[]) {

1613 if (projects.length === 0) return null

1614

1615 let latest = projects[0]

1616

1617 for (let i = 1; i < projects.length; i++) {

1618 if (projects[i].updatedAt > latest.updatedAt) {

1619 latest = projects[i]

1620 }

1621 }

1622

1623 return latest

1624}

1625

1626function getOldestAndNewest(projects: Project[]) {

1627 if (projects.length === 0) return { oldest: null, newest: null }

1628

1629 let oldest = projects[0]

1630 let newest = projects[0]

1631

1632 for (let i = 1; i < projects.length; i++) {

1633 if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]

1634 if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]

1635 }

1636

1637 return { oldest, newest }

1638}

1639```

1640

1641Single pass through the array, no copying, no sorting.

1642

1643**Alternative (Math.min/Math.max for small arrays):**

1644

1645```typescript

1646const numbers = [5, 2, 8, 1, 9]

1647const min = Math.min(...numbers)

1648const max = Math.max(...numbers)

1649```

1650

1651This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.

1652

1653

1654

1655## Defer Non-Critical Work with requestIdleCallback

1656

1657**Impact: MEDIUM (keeps UI responsive during background tasks)**

1658

1659Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.

1660

1661**Incorrect (blocks main thread during user interaction):**

1662

1663```typescript

1664function handleSearch(query: string) {

1665 const results = searchItems(query)

1666 setResults(results)

1667

1668 // These block the main thread immediately

1669 analytics.track('search', { query })

1670 saveToRecentSearches(query)

1671 prefetchTopResults(results.slice(0, 3))

1672}

1673```

1674

1675**Correct (defers non-critical work to idle time):**

1676

1677```typescript

1678function handleSearch(query: string) {

1679 const results = searchItems(query)

1680 setResults(results)

1681

1682 // Defer non-critical work to idle periods

1683 requestIdleCallback(() => {

1684 analytics.track('search', { query })

1685 })

1686

1687 requestIdleCallback(() => {

1688 saveToRecentSearches(query)

1689 })

1690

1691 requestIdleCallback(() => {

1692 prefetchTopResults(results.slice(0, 3))

1693 })

1694}

1695```

1696

1697**With timeout for required work:**

1698

1699```typescript

1700// Ensure analytics fires within 2 seconds even if browser stays busy

1701requestIdleCallback(

1702 () => analytics.track('page_view', { path: location.pathname }),

1703 { timeout: 2000 }

1704)

1705```

1706

1707**Chunking large tasks:**

1708

1709```typescript

1710function processLargeDataset(items: Item[]) {

1711 let index = 0

1712

1713 function processChunk(deadline: IdleDeadline) {

1714 // Process items while we have idle time (aim for <50ms chunks)

1715 while (index < items.length && deadline.timeRemaining() > 0) {

1716 processItem(items[index])

1717 index++

1718 }

1719

1720 // Schedule next chunk if more items remain

1721 if (index < items.length) {

1722 requestIdleCallback(processChunk)

1723 }

1724 }

1725

1726 requestIdleCallback(processChunk)

1727}

1728```

1729

1730**With fallback for unsupported browsers:**

1731

1732```typescript

1733const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))

1734

1735scheduleIdleWork(() => {

1736 // Non-critical work

1737})

1738```

1739

1740**When to use:**

1741

1742- Analytics and telemetry

1743- Saving state to localStorage/IndexedDB

1744- Prefetching resources for likely next actions

1745- Processing non-urgent data transformations

1746- Lazy initialization of non-critical features

1747

1748**When NOT to use:**

1749

1750- User-initiated actions that need immediate feedback

1751- Rendering updates the user is waiting for

1752- Time-sensitive operations

1753

1754

1755

1756## Use Set/Map for O(1) Lookups

1757

1758Convert arrays to Set/Map for repeated membership checks.

1759

1760**Incorrect (O(n) per check):**

1761

1762```typescript

1763const allowedIds = ['a', 'b', 'c', ...]

1764items.filter(item => allowedIds.includes(item.id))

1765```

1766

1767**Correct (O(1) per check):**

1768

1769```typescript

1770const allowedIds = new Set(['a', 'b', 'c', ...])

1771items.filter(item => allowedIds.has(item.id))

1772```

1773

1774

1775

1776## Use toSorted() Instead of sort() for Immutability

1777

1778`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.

1779

1780**Incorrect (mutates original array):**

1781

1782```typescript

1783function UserList({ users }: { users: User[] }) {

1784 // Mutates the users prop array!

1785 const sorted = useMemo(

1786 () => users.sort((a, b) => a.name.localeCompare(b.name)),

1787 [users]

1788 )

1789 return <div>{sorted.map(renderUser)}</div>

1790}

1791```

1792

1793**Correct (creates new array):**

1794

1795```typescript

1796function UserList({ users }: { users: User[] }) {

1797 // Creates new sorted array, original unchanged

1798 const sorted = useMemo(

1799 () => users.toSorted((a, b) => a.name.localeCompare(b.name)),

1800 [users]

1801 )

1802 return <div>{sorted.map(renderUser)}</div>

1803}

1804```

1805

1806**Why this matters in React:**

1807

18081. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only

18092. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior

1810

1811**Browser support (fallback for older browsers):**

1812

1813`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:

1814

1815```typescript

1816// Fallback for older browsers

1817const sorted = [...items].sort((a, b) => a.value - b.value)

1818```

1819

1820**Other immutable array methods:**

1821

1822- `.toSorted()` - immutable sort

1823- `.toReversed()` - immutable reverse

1824- `.toSpliced()` - immutable splice

1825- `.with()` - immutable element replacement

1826

1827

1828

1829## Use Activity Component for Show/Hide

1830

1831Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.

1832

1833**Usage:**

1834

1835```tsx

1836import { Activity } from 'react'

1837

1838function Dropdown({ isOpen }: Props) {

1839 return (

1840 <Activity mode={isOpen ? 'visible' : 'hidden'}>

1841 <ExpensiveMenu />

1842 </Activity>

1843 )

1844}

1845```

1846

1847Avoids expensive re-renders and state loss.

1848

1849

1850

1851## Animate SVG Wrapper Instead of SVG Element

1852

1853Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.

1854

1855**Incorrect (animating SVG directly - no hardware acceleration):**

1856

1857```tsx

1858function LoadingSpinner() {

1859 return (

1860 <svg

1861 className="animate-spin"

1862 width="24"

1863 height="24"

1864 viewBox="0 0 24 24"

1865 >

1866 <circle cx="12" cy="12" r="10" stroke="currentColor" />

1867 </svg>

1868 )

1869}

1870```

1871

1872**Correct (animating wrapper div - hardware accelerated):**

1873

1874```tsx

1875function LoadingSpinner() {

1876 return (

1877 <div className="animate-spin">

1878 <svg

1879 width="24"

1880 height="24"

1881 viewBox="0 0 24 24"

1882 >

1883 <circle cx="12" cy="12" r="10" stroke="currentColor" />

1884 </svg>

1885 </div>

1886 )

1887}

1888```

1889

1890This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.

1891

1892

1893

1894## Use Explicit Conditional Rendering

1895

1896Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.

1897

1898**Incorrect (renders "0" when count is 0):**

1899

1900```tsx

1901function Badge({ count }: { count: number }) {

1902 return (

1903 <div>

1904 {count && <span className="badge">{count}</span>}

1905 </div>

1906 )

1907}

1908

1909// When count = 0, renders: <div>0</div>

1910// When count = 5, renders: <div><span class="badge">5</span></div>

1911```

1912

1913**Correct (renders nothing when count is 0):**

1914

1915```tsx

1916function Badge({ count }: { count: number }) {

1917 return (

1918 <div>

1919 {count > 0 ? <span className="badge">{count}</span> : null}

1920 </div>

1921 )

1922}

1923

1924// When count = 0, renders: <div></div>

1925// When count = 5, renders: <div><span class="badge">5</span></div>

1926```

1927

1928

1929

1930## CSS content-visibility for Long Lists

1931

1932Apply `content-visibility: auto` to defer off-screen rendering.

1933

1934**CSS:**

1935

1936```css

1937.message-item {

1938 content-visibility: auto;

1939 contain-intrinsic-size: 0 80px;

1940}

1941```

1942

1943**Example:**

1944

1945```tsx

1946function MessageList({ messages }: { messages: Message[] }) {

1947 return (

1948 <div className="overflow-y-auto h-screen">

1949 {messages.map(msg => (

1950 <div key={msg.id} className="message-item">

1951 <Avatar user={msg.author} />

1952 <div>{msg.content}</div>

1953 </div>

1954 ))}

1955 </div>

1956 )

1957}

1958```

1959

1960For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).

1961

1962

1963

1964## Hoist Static JSX Elements

1965

1966Extract static JSX outside components to avoid re-creation.

1967

1968**Incorrect (recreates element every render):**

1969

1970```tsx

1971function LoadingSkeleton() {

1972 return <div className="animate-pulse h-20 bg-gray-200" />

1973}

1974

1975function Container() {

1976 return (

1977 <div>

1978 {loading && <LoadingSkeleton />}

1979 </div>

1980 )

1981}

1982```

1983

1984**Correct (reuses same element):**

1985

1986```tsx

1987const loadingSkeleton = (

1988 <div className="animate-pulse h-20 bg-gray-200" />

1989)

1990

1991function Container() {

1992 return (

1993 <div>

1994 {loading && loadingSkeleton}

1995 </div>

1996 )

1997}

1998```

1999

2000This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.

2001

2002**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.

2003

2004

2005

2006## Prevent Hydration Mismatch Without Flickering

2007

2008When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.

2009

2010**Incorrect (breaks SSR):**

2011

2012```tsx

2013function ThemeWrapper({ children }: { children: ReactNode }) {

2014 // localStorage is not available on server - throws error

2015 const theme = localStorage.getItem('theme') || 'light'

2016

2017 return (

2018 <div className={theme}>

2019 {children}

2020 </div>

2021 )

2022}

2023```

2024

2025Server-side rendering will fail because `localStorage` is undefined.

2026

2027**Incorrect (visual flickering):**

2028

2029```tsx

2030function ThemeWrapper({ children }: { children: ReactNode }) {

2031 const [theme, setTheme] = useState('light')

2032

2033 useEffect(() => {

2034 // Runs after hydration - causes visible flash

2035 const stored = localStorage.getItem('theme')

2036 if (stored) {

2037 setTheme(stored)

2038 }

2039 }, [])

2040

2041 return (

2042 <div className={theme}>

2043 {children}

2044 </div>

2045 )

2046}

2047```

2048

2049Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.

2050

2051**Correct (no flicker, no hydration mismatch):**

2052

2053```tsx

2054function ThemeWrapper({ children }: { children: ReactNode }) {

2055 return (

2056 <>

2057 <div id="theme-wrapper">

2058 {children}

2059 </div>

2060 <script

2061 dangerouslySetInnerHTML={{

2062 __html: `

2063 (function() {

2064 try {

2065 var theme = localStorage.getItem('theme') || 'light';

2066 var el = document.getElementById('theme-wrapper');

2067 if (el) el.className = theme;

2068 } catch (e) {}

2069 })();

2070 `,

2071 }}

2072 />

2073 </>

2074 )

2075}

2076```

2077

2078The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.

2079

2080This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.

2081

2082

2083

2084## Suppress Expected Hydration Mismatches

2085

2086In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.

2087

2088**Incorrect (known mismatch warnings):**

2089

2090```tsx

2091function Timestamp() {

2092 return <span>{new Date().toLocaleString()}</span>

2093}

2094```

2095

2096**Correct (suppress expected mismatch only):**

2097

2098```tsx

2099function Timestamp() {

2100 return (

2101 <span suppressHydrationWarning>

2102 {new Date().toLocaleString()}

2103 </span>

2104 )

2105}

2106```

2107

2108

2109

2110## Use React DOM Resource Hints

2111

2112**Impact: HIGH (reduces load time for critical resources)**

2113

2114React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.

2115

2116- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to

2117- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server

2118- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon

2119- **`preloadModule(href)`**: Fetch an ES module you'll use soon

2120- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script

2121- **`preinitModule(href)`**: Fetch and evaluate an ES module

2122

2123**Example (preconnect to third-party APIs):**

2124

2125```tsx

2126import { preconnect, prefetchDNS } from 'react-dom'

2127

2128export default function App() {

2129 prefetchDNS('https://analytics.example.com')

2130 preconnect('https://api.example.com')

2131

2132 return <main>{/* content */}</main>

2133}

2134```

2135

2136**Example (preload critical fonts and styles):**

2137

2138```tsx

2139import { preload, preinit } from 'react-dom'

2140

2141export default function RootLayout({ children }) {

2142 // Preload font file

2143 preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })

2144

2145 // Fetch and apply critical stylesheet immediately

2146 preinit('/styles/critical.css', { as: 'style' })

2147

2148 return (

2149 <html>

2150 <body>{children}</body>

2151 </html>

2152 )

2153}

2154```

2155

2156**Example (preload modules for code-split routes):**

2157

2158```tsx

2159import { preloadModule, preinitModule } from 'react-dom'

2160

2161function Navigation() {

2162 const preloadDashboard = () => {

2163 preloadModule('/dashboard.js', { as: 'script' })

2164 }

2165

2166 return (

2167 <nav>

2168 <a href="/dashboard" onMouseEnter={preloadDashboard}>

2169 Dashboard

2170 </a>

2171 </nav>

2172 )

2173}

2174```

2175

2176**When to use each:**

2177

2178| API | Use case |

2179|-----|----------|

2180| `prefetchDNS` | Third-party domains you'll connect to later |

2181| `preconnect` | APIs or CDNs you'll fetch from immediately |

2182| `preload` | Critical resources needed for current page |

2183| `preloadModule` | JS modules for likely next navigation |

2184| `preinit` | Stylesheets/scripts that must execute early |

2185| `preinitModule` | ES modules that must execute early |

2186

2187Reference: [React DOM Resource Preloading APIs](https://react.dev/reference/react-dom#resource-preloading-apis)

2188

2189

2190

2191## Use defer or async on Script Tags

2192

2193**Impact: HIGH (eliminates render-blocking)**

2194

2195Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.

2196

2197- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order

2198- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order

2199

2200Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.

2201

2202**Incorrect (blocks rendering):**

2203

2204```tsx

2205export default function Document() {

2206 return (

2207 <html>

2208 <head>

2209 <script src="https://example.com/analytics.js" />

2210 <script src="/scripts/utils.js" />

2211 </head>

2212 <body>{/* content */}</body>

2213 </html>

2214 )

2215}

2216```

2217

2218**Correct (non-blocking):**

2219

2220```tsx

2221export default function Document() {

2222 return (

2223 <html>

2224 <head>

2225 {/* Independent script - use async */}

2226 <script src="https://example.com/analytics.js" async />

2227 {/* DOM-dependent script - use defer */}

2228 <script src="/scripts/utils.js" defer />

2229 </head>

2230 <body>{/* content */}</body>

2231 </html>

2232 )

2233}

2234```

2235

2236**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:

2237

2238```tsx

2239import Script from 'next/script'

2240

2241export default function Page() {

2242 return (

2243 <>

2244 <Script src="https://example.com/analytics.js" strategy="afterInteractive" />

2245 <Script src="/scripts/utils.js" strategy="beforeInteractive" />

2246 </>

2247 )

2248}

2249```

2250

2251Reference: [MDN - Script element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)

2252

2253

2254

2255## Optimize SVG Precision

2256

2257Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.

2258

2259**Incorrect (excessive precision):**

2260

2261```svg

2262<path d="M 10.293847 20.847362 L 30.938472 40.192837" />

2263```

2264

2265**Correct (1 decimal place):**

2266

2267```svg

2268<path d="M 10.3 20.8 L 30.9 40.2" />

2269```

2270

2271**Automate with SVGO:**

2272

2273```bash

2274npx svgo --precision=1 --multipass icon.svg

2275```

2276

2277

2278

2279## Use useTransition Over Manual Loading States

2280

2281Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.

2282

2283**Incorrect (manual loading state):**

2284

2285```tsx

2286function SearchResults() {

2287 const [query, setQuery] = useState('')

2288 const [results, setResults] = useState([])

2289 const [isLoading, setIsLoading] = useState(false)

2290

2291 const handleSearch = async (value: string) => {

2292 setIsLoading(true)

2293 setQuery(value)

2294 const data = await fetchResults(value)

2295 setResults(data)

2296 setIsLoading(false)

2297 }

2298

2299 return (

2300 <>

2301 <input onChange={(e) => handleSearch(e.target.value)} />

2302 {isLoading && <Spinner />}

2303 <ResultsList results={results} />

2304 </>

2305 )

2306}

2307```

2308

2309**Correct (useTransition with built-in pending state):**

2310

2311```tsx

2312import { useTransition, useState } from 'react'

2313

2314function SearchResults() {

2315 const [query, setQuery] = useState('')

2316 const [results, setResults] = useState([])

2317 const [isPending, startTransition] = useTransition()

2318

2319 const handleSearch = (value: string) => {

2320 setQuery(value) // Update input immediately

2321

2322 startTransition(async () => {

2323 // Fetch and update results

2324 const data = await fetchResults(value)

2325 setResults(data)

2326 })

2327 }

2328

2329 return (

2330 <>

2331 <input onChange={(e) => handleSearch(e.target.value)} />

2332 {isPending && <Spinner />}

2333 <ResultsList results={results} />

2334 </>

2335 )

2336}

2337```

2338

2339**Benefits:**

2340

2341- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`

2342- **Error resilience**: Pending state correctly resets even if the transition throws

2343- **Better responsiveness**: Keeps the UI responsive during updates

2344- **Interrupt handling**: New transitions automatically cancel pending ones

2345

2346Reference: [useTransition](https://react.dev/reference/react/useTransition)

2347

2348

2349

2350## Defer State Reads to Usage Point

2351

2352Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.

2353

2354**Incorrect (subscribes to all searchParams changes):**

2355

2356```tsx

2357function ShareButton({ chatId }: { chatId: string }) {

2358 const searchParams = useSearchParams()

2359

2360 const handleShare = () => {

2361 const ref = searchParams.get('ref')

2362 shareChat(chatId, { ref })

2363 }

2364

2365 return <button onClick={handleShare}>Share</button>

2366}

2367```

2368

2369**Correct (reads on demand, no subscription):**

2370

2371```tsx

2372function ShareButton({ chatId }: { chatId: string }) {

2373 const handleShare = () => {

2374 const params = new URLSearchParams(window.location.search)

2375 const ref = params.get('ref')

2376 shareChat(chatId, { ref })

2377 }

2378

2379 return <button onClick={handleShare}>Share</button>

2380}

2381```

2382

2383

2384

2385## Narrow Effect Dependencies

2386

2387Specify primitive dependencies instead of objects to minimize effect re-runs.

2388

2389**Incorrect (re-runs on any user field change):**

2390

2391```tsx

2392useEffect(() => {

2393 console.log(user.id)

2394}, [user])

2395```

2396

2397**Correct (re-runs only when id changes):**

2398

2399```tsx

2400useEffect(() => {

2401 console.log(user.id)

2402}, [user.id])

2403```

2404

2405**For derived state, compute outside effect:**

2406

2407```tsx

2408// Incorrect: runs on width=767, 766, 765...

2409useEffect(() => {

2410 if (width < 768) {

2411 enableMobileMode()

2412 }

2413}, [width])

2414

2415// Correct: runs only on boolean transition

2416const isMobile = width < 768

2417useEffect(() => {

2418 if (isMobile) {

2419 enableMobileMode()

2420 }

2421}, [isMobile])

2422```

2423

2424

2425

2426## Calculate Derived State During Rendering

2427

2428If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.

2429

2430**Incorrect (redundant state and effect):**

2431

2432```tsx

2433function Form() {

2434 const [firstName, setFirstName] = useState('First')

2435 const [lastName, setLastName] = useState('Last')

2436 const [fullName, setFullName] = useState('')

2437

2438 useEffect(() => {

2439 setFullName(firstName + ' ' + lastName)

2440 }, [firstName, lastName])

2441

2442 return <p>{fullName}</p>

2443}

2444```

2445

2446**Correct (derive during render):**

2447

2448```tsx

2449function Form() {

2450 const [firstName, setFirstName] = useState('First')

2451 const [lastName, setLastName] = useState('Last')

2452 const fullName = firstName + ' ' + lastName

2453

2454 return <p>{fullName}</p>

2455}

2456```

2457

2458References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)

2459

2460

2461

2462## Subscribe to Derived State

2463

2464Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.

2465

2466**Incorrect (re-renders on every pixel change):**

2467

2468```tsx

2469function Sidebar() {

2470 const width = useWindowWidth() // updates continuously

2471 const isMobile = width < 768

2472 return <nav className={isMobile ? 'mobile' : 'desktop'} />

2473}

2474```

2475

2476**Correct (re-renders only when boolean changes):**

2477

2478```tsx

2479function Sidebar() {

2480 const isMobile = useMediaQuery('(max-width: 767px)')

2481 return <nav className={isMobile ? 'mobile' : 'desktop'} />

2482}

2483```

2484

2485

2486

2487## Use Functional setState Updates

2488

2489When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.

2490

2491**Incorrect (requires state as dependency):**

2492

2493```tsx

2494function TodoList() {

2495 const [items, setItems] = useState(initialItems)

2496

2497 // Callback must depend on items, recreated on every items change

2498 const addItems = useCallback((newItems: Item[]) => {

2499 setItems([...items, ...newItems])

2500 }, [items]) // ❌ items dependency causes recreations

2501

2502 // Risk of stale closure if dependency is forgotten

2503 const removeItem = useCallback((id: string) => {

2504 setItems(items.filter(item => item.id !== id))

2505 }, []) // ❌ Missing items dependency - will use stale items!

2506

2507 return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />

2508}

2509```

2510

2511The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.

2512

2513**Correct (stable callbacks, no stale closures):**

2514

2515```tsx

2516function TodoList() {

2517 const [items, setItems] = useState(initialItems)

2518

2519 // Stable callback, never recreated

2520 const addItems = useCallback((newItems: Item[]) => {

2521 setItems(curr => [...curr, ...newItems])

2522 }, []) // ✅ No dependencies needed

2523

2524 // Always uses latest state, no stale closure risk

2525 const removeItem = useCallback((id: string) => {

2526 setItems(curr => curr.filter(item => item.id !== id))

2527 }, []) // ✅ Safe and stable

2528

2529 return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />

2530}

2531```

2532

2533**Benefits:**

2534

25351. **Stable callback references** - Callbacks don't need to be recreated when state changes

25362. **No stale closures** - Always operates on the latest state value

25373. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks

25384. **Prevents bugs** - Eliminates the most common source of React closure bugs

2539

2540**When to use functional updates:**

2541

2542- Any setState that depends on the current state value

2543- Inside useCallback/useMemo when state is needed

2544- Event handlers that reference state

2545- Async operations that update state

2546

2547**When direct updates are fine:**

2548

2549- Setting state to a static value: `setCount(0)`

2550- Setting state from props/arguments only: `setName(newName)`

2551- State doesn't depend on previous value

2552

2553**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.

2554

2555

2556

2557## Use Lazy State Initialization

2558

2559Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.

2560

2561**Incorrect (runs on every render):**

2562

2563```tsx

2564function FilteredList({ items }: { items: Item[] }) {

2565 // buildSearchIndex() runs on EVERY render, even after initialization

2566 const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))

2567 const [query, setQuery] = useState('')

2568

2569 // When query changes, buildSearchIndex runs again unnecessarily

2570 return <SearchResults index={searchIndex} query={query} />

2571}

2572

2573function UserProfile() {

2574 // JSON.parse runs on every render

2575 const [settings, setSettings] = useState(

2576 JSON.parse(localStorage.getItem('settings') || '{}')

2577 )

2578

2579 return <SettingsForm settings={settings} onChange={setSettings} />

2580}

2581```

2582

2583**Correct (runs only once):**

2584

2585```tsx

2586function FilteredList({ items }: { items: Item[] }) {

2587 // buildSearchIndex() runs ONLY on initial render

2588 const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))

2589 const [query, setQuery] = useState('')

2590

2591 return <SearchResults index={searchIndex} query={query} />

2592}

2593

2594function UserProfile() {

2595 // JSON.parse runs only on initial render

2596 const [settings, setSettings] = useState(() => {

2597 const stored = localStorage.getItem('settings')

2598 return stored ? JSON.parse(stored) : {}

2599 })

2600

2601 return <SettingsForm settings={settings} onChange={setSettings} />

2602}

2603```

2604

2605Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.

2606

2607For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.

2608

2609

2610

2611## Extract Default Non-primitive Parameter Value from Memoized Component to Constant

2612

2613When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.

2614

2615To address this issue, extract the default value into a constant.

2616

2617**Incorrect (`onClick` has different values on every rerender):**

2618

2619```tsx

2620const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {

2621 // ...

2622})

2623

2624// Used without optional onClick

2625<UserAvatar />

2626```

2627

2628**Correct (stable default value):**

2629

2630```tsx

2631const NOOP = () => {};

2632

2633const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {

2634 // ...

2635})

2636

2637// Used without optional onClick

2638<UserAvatar />

2639```

2640

2641

2642

2643## Extract to Memoized Components

2644

2645Extract expensive work into memoized components to enable early returns before computation.

2646

2647**Incorrect (computes avatar even when loading):**

2648

2649```tsx

2650function Profile({ user, loading }: Props) {

2651 const avatar = useMemo(() => {

2652 const id = computeAvatarId(user)

2653 return <Avatar id={id} />

2654 }, [user])

2655

2656 if (loading) return <Skeleton />

2657 return <div>{avatar}</div>

2658}

2659```

2660

2661**Correct (skips computation when loading):**

2662

2663```tsx

2664const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {

2665 const id = useMemo(() => computeAvatarId(user), [user])

2666 return <Avatar id={id} />

2667})

2668

2669function Profile({ user, loading }: Props) {

2670 if (loading) return <Skeleton />

2671 return (

2672 <div>

2673 <UserAvatar user={user} />

2674 </div>

2675 )

2676}

2677```

2678

2679**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.

2680

2681

2682

2683## Put Interaction Logic in Event Handlers

2684

2685If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.

2686

2687**Incorrect (event modeled as state + effect):**

2688

2689```tsx

2690function Form() {

2691 const [submitted, setSubmitted] = useState(false)

2692 const theme = useContext(ThemeContext)

2693

2694 useEffect(() => {

2695 if (submitted) {

2696 post('/api/register')

2697 showToast('Registered', theme)

2698 }

2699 }, [submitted, theme])

2700

2701 return <button onClick={() => setSubmitted(true)}>Submit</button>

2702}

2703```

2704

2705**Correct (do it in the handler):**

2706

2707```tsx

2708function Form() {

2709 const theme = useContext(ThemeContext)

2710

2711 function handleSubmit() {

2712 post('/api/register')

2713 showToast('Registered', theme)

2714 }

2715

2716 return <button onClick={handleSubmit}>Submit</button>

2717}

2718```

2719

2720Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)

2721

2722

2723

2724## Don't Define Components Inside Components

2725

2726**Impact: HIGH (prevents remount on every render)**

2727

2728Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.

2729

2730A common reason developers do this is to access parent variables without passing props. Always pass props instead.

2731

2732**Incorrect (remounts on every render):**

2733

2734```tsx

2735function UserProfile({ user, theme }) {

2736 // Defined inside to access `theme` - BAD

2737 const Avatar = () => (

2738 <img

2739 src={user.avatarUrl}

2740 className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}

2741 />

2742 )

2743

2744 // Defined inside to access `user` - BAD

2745 const Stats = () => (

2746 <div>

2747 <span>{user.followers} followers</span>

2748 <span>{user.posts} posts</span>

2749 </div>

2750 )

2751

2752 return (

2753 <div>

2754 <Avatar />

2755 <Stats />

2756 </div>

2757 )

2758}

2759```

2760

2761Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.

2762

2763**Correct (pass props instead):**

2764

2765```tsx

2766function Avatar({ src, theme }: { src: string; theme: string }) {

2767 return (

2768 <img

2769 src={src}

2770 className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}

2771 />

2772 )

2773}

2774

2775function Stats({ followers, posts }: { followers: number; posts: number }) {

2776 return (

2777 <div>

2778 <span>{followers} followers</span>

2779 <span>{posts} posts</span>

2780 </div>

2781 )

2782}

2783

2784function UserProfile({ user, theme }) {

2785 return (

2786 <div>

2787 <Avatar src={user.avatarUrl} theme={theme} />

2788 <Stats followers={user.followers} posts={user.posts} />

2789 </div>

2790 )

2791}

2792```

2793

2794**Symptoms of this bug:**

2795- Input fields lose focus on every keystroke

2796- Animations restart unexpectedly

2797- `useEffect` cleanup/setup runs on every parent render

2798- Scroll position resets inside the component

2799

2800

2801

2802## Do not wrap a simple expression with a primitive result type in useMemo

2803

2804When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.

2805Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.

2806

2807**Incorrect:**

2808

2809```tsx

2810function Header({ user, notifications }: Props) {

2811 const isLoading = useMemo(() => {

2812 return user.isLoading || notifications.isLoading

2813 }, [user.isLoading, notifications.isLoading])

2814

2815 if (isLoading) return <Skeleton />

2816 // return some markup

2817}

2818```

2819

2820**Correct:**

2821

2822```tsx

2823function Header({ user, notifications }: Props) {

2824 const isLoading = user.isLoading || notifications.isLoading

2825

2826 if (isLoading) return <Skeleton />

2827 // return some markup

2828}

2829```

2830

2831

2832

2833## Split Combined Hook Computations

2834

2835When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.

2836

2837**Incorrect (changing `sortOrder` recomputes filtering):**

2838

2839```tsx

2840const sortedProducts = useMemo(() => {

2841 const filtered = products.filter((p) => p.category === category)

2842 const sorted = filtered.toSorted((a, b) =>

2843 sortOrder === "asc" ? a.price - b.price : b.price - a.price

2844 )

2845 return sorted

2846}, [products, category, sortOrder])

2847```

2848

2849**Correct (filtering only recomputes when products or category change):**

2850

2851```tsx

2852const filteredProducts = useMemo(

2853 () => products.filter((p) => p.category === category),

2854 [products, category]

2855)

2856

2857const sortedProducts = useMemo(

2858 () =>

2859 filteredProducts.toSorted((a, b) =>

2860 sortOrder === "asc" ? a.price - b.price : b.price - a.price

2861 ),

2862 [filteredProducts, sortOrder]

2863)

2864```

2865

2866This pattern also applies to `useEffect` when combining unrelated side effects:

2867

2868**Incorrect (both effects run when either dependency changes):**

2869

2870```tsx

2871useEffect(() => {

2872 analytics.trackPageView(pathname)

2873 document.title = `${pageTitle} | My App`

2874}, [pathname, pageTitle])

2875```

2876

2877**Correct (effects run independently):**

2878

2879```tsx

2880useEffect(() => {

2881 analytics.trackPageView(pathname)

2882}, [pathname])

2883

2884useEffect(() => {

2885 document.title = `${pageTitle} | My App`

2886}, [pageTitle])

2887```

2888

2889**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.

2890

2891

2892

2893## Use Transitions for Non-Urgent Updates

2894

2895Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.

2896

2897**Incorrect (blocks UI on every scroll):**

2898

2899```tsx

2900function ScrollTracker() {

2901 const [scrollY, setScrollY] = useState(0)

2902 useEffect(() => {

2903 const handler = () => setScrollY(window.scrollY)

2904 window.addEventListener('scroll', handler, { passive: true })

2905 return () => window.removeEventListener('scroll', handler)

2906 }, [])

2907}

2908```

2909

2910**Correct (non-blocking updates):**

2911

2912```tsx

2913import { startTransition } from 'react'

2914

2915function ScrollTracker() {

2916 const [scrollY, setScrollY] = useState(0)

2917 useEffect(() => {

2918 const handler = () => {

2919 startTransition(() => setScrollY(window.scrollY))

2920 }

2921 window.addEventListener('scroll', handler, { passive: true })

2922 return () => window.removeEventListener('scroll', handler)

2923 }, [])

2924}

2925```

2926

2927

2928

2929## Use useDeferredValue for Expensive Derived Renders

2930

2931When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.

2932

2933**Incorrect (input feels laggy while filtering):**

2934

2935```tsx

2936function Search({ items }: { items: Item[] }) {

2937 const [query, setQuery] = useState('')

2938 const filtered = items.filter(item => fuzzyMatch(item, query))

2939

2940 return (

2941 <>

2942 <input value={query} onChange={e => setQuery(e.target.value)} />

2943 <ResultsList results={filtered} />

2944 </>

2945 )

2946}

2947```

2948

2949**Correct (input stays snappy, results render when ready):**

2950

2951```tsx

2952function Search({ items }: { items: Item[] }) {

2953 const [query, setQuery] = useState('')

2954 const deferredQuery = useDeferredValue(query)

2955 const filtered = useMemo(

2956 () => items.filter(item => fuzzyMatch(item, deferredQuery)),

2957 [items, deferredQuery]

2958 )

2959 const isStale = query !== deferredQuery

2960

2961 return (

2962 <>

2963 <input value={query} onChange={e => setQuery(e.target.value)} />

2964 <div style={{ opacity: isStale ? 0.7 : 1 }}>

2965 <ResultsList results={filtered} />

2966 </div>

2967 </>

2968 )

2969}

2970```

2971

2972**When to use:**

2973

2974- Filtering/searching large lists

2975- Expensive visualizations (charts, graphs) reacting to input

2976- Any derived state that causes noticeable render delays

2977

2978**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.

2979

2980Reference: [React useDeferredValue](https://react.dev/reference/react/useDeferredValue)

2981

2982

2983

2984## Use useRef for Transient Values

2985

2986When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.

2987

2988**Incorrect (renders every update):**

2989

2990```tsx

2991function Tracker() {

2992 const [lastX, setLastX] = useState(0)

2993

2994 useEffect(() => {

2995 const onMove = (e: MouseEvent) => setLastX(e.clientX)

2996 window.addEventListener('mousemove', onMove)

2997 return () => window.removeEventListener('mousemove', onMove)

2998 }, [])

2999

3000 return (

3001 <div

3002 style={{

3003 position: 'fixed',

3004 top: 0,

3005 left: lastX,

3006 width: 8,

3007 height: 8,

3008 background: 'black',

3009 }}

3010 />

3011 )

3012}

3013```

3014

3015**Correct (no re-render for tracking):**

3016

3017```tsx

3018function Tracker() {

3019 const lastXRef = useRef(0)

3020 const dotRef = useRef<HTMLDivElement>(null)

3021

3022 useEffect(() => {

3023 const onMove = (e: MouseEvent) => {

3024 lastXRef.current = e.clientX

3025 const node = dotRef.current

3026 if (node) {

3027 node.style.transform = `translateX(${e.clientX}px)`

3028 }

3029 }

3030 window.addEventListener('mousemove', onMove)

3031 return () => window.removeEventListener('mousemove', onMove)

3032 }, [])

3033

3034 return (

3035 <div

3036 ref={dotRef}

3037 style={{

3038 position: 'fixed',

3039 top: 0,

3040 left: 0,

3041 width: 8,

3042 height: 8,

3043 background: 'black',

3044 transform: 'translateX(0px)',

3045 }}

3046 />

3047 )

3048}

3049```

3050

3051

3052

3053## Use after() for Non-Blocking Operations

3054

3055Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.

3056

3057**Incorrect (blocks response):**

3058

3059```tsx

3060import { logUserAction } from '@/app/utils'

3061

3062export async function POST(request: Request) {

3063 // Perform mutation

3064 await updateDatabase(request)

3065

3066 // Logging blocks the response

3067 const userAgent = request.headers.get('user-agent') || 'unknown'

3068 await logUserAction({ userAgent })

3069

3070 return new Response(JSON.stringify({ status: 'success' }), {

3071 status: 200,

3072 headers: { 'Content-Type': 'application/json' }

3073 })

3074}

3075```

3076

3077**Correct (non-blocking):**

3078

3079```tsx

3080import { after } from 'next/server'

3081import { headers, cookies } from 'next/headers'

3082import { logUserAction } from '@/app/utils'

3083

3084export async function POST(request: Request) {

3085 // Perform mutation

3086 await updateDatabase(request)

3087

3088 // Log after response is sent

3089 after(async () => {

3090 const userAgent = (await headers()).get('user-agent') || 'unknown'

3091 const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'

3092

3093 logUserAction({ sessionCookie, userAgent })

3094 })

3095

3096 return new Response(JSON.stringify({ status: 'success' }), {

3097 status: 200,

3098 headers: { 'Content-Type': 'application/json' }

3099 })

3100}

3101```

3102

3103The response is sent immediately while logging happens in the background.

3104

3105**Common use cases:**

3106

3107- Analytics tracking

3108- Audit logging

3109- Sending notifications

3110- Cache invalidation

3111- Cleanup tasks

3112

3113**Important notes:**

3114

3115- `after()` runs even if the response fails or redirects

3116- Works in Server Actions, Route Handlers, and Server Components

3117

3118Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)

3119

3120

3121

3122## Authenticate Server Actions Like API Routes

3123

3124**Impact: CRITICAL (prevents unauthorized access to server mutations)**

3125

3126Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.

3127

3128Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."

3129

3130**Incorrect (no authentication check):**

3131

3132```typescript

3133'use server'

3134

3135export async function deleteUser(userId: string) {

3136 // Anyone can call this! No auth check

3137 await db.user.delete({ where: { id: userId } })

3138 return { success: true }

3139}

3140```

3141

3142**Correct (authentication inside the action):**

3143

3144```typescript

3145'use server'

3146

3147import { verifySession } from '@/lib/auth'

3148import { unauthorized } from '@/lib/errors'

3149

3150export async function deleteUser(userId: string) {

3151 // Always check auth inside the action

3152 const session = await verifySession()

3153

3154 if (!session) {

3155 throw unauthorized('Must be logged in')

3156 }

3157

3158 // Check authorization too

3159 if (session.user.role !== 'admin' && session.user.id !== userId) {

3160 throw unauthorized('Cannot delete other users')

3161 }

3162

3163 await db.user.delete({ where: { id: userId } })

3164 return { success: true }

3165}

3166```

3167

3168**With input validation:**

3169

3170```typescript

3171'use server'

3172

3173import { verifySession } from '@/lib/auth'

3174import { z } from 'zod'

3175

3176const updateProfileSchema = z.object({

3177 userId: z.string().uuid(),

3178 name: z.string().min(1).max(100),

3179 email: z.string().email()

3180})

3181

3182export async function updateProfile(data: unknown) {

3183 // Validate input first

3184 const validated = updateProfileSchema.parse(data)

3185

3186 // Then authenticate

3187 const session = await verifySession()

3188 if (!session) {

3189 throw new Error('Unauthorized')

3190 }

3191

3192 // Then authorize

3193 if (session.user.id !== validated.userId) {

3194 throw new Error('Can only update own profile')

3195 }

3196

3197 // Finally perform the mutation

3198 await db.user.update({

3199 where: { id: validated.userId },

3200 data: {

3201 name: validated.name,

3202 email: validated.email

3203 }

3204 })

3205

3206 return { success: true }

3207}

3208```

3209

3210Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)

3211

3212

3213

3214## Cross-Request LRU Caching

3215

3216`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.

3217

3218**Implementation:**

3219

3220```typescript

3221import { LRUCache } from 'lru-cache'

3222

3223const cache = new LRUCache<string, any>({

3224 max: 1000,

3225 ttl: 5 * 60 * 1000 // 5 minutes

3226})

3227

3228export async function getUser(id: string) {

3229 const cached = cache.get(id)

3230 if (cached) return cached

3231

3232 const user = await db.user.findUnique({ where: { id } })

3233 cache.set(id, user)

3234 return user

3235}

3236

3237// Request 1: DB query, result cached

3238// Request 2: cache hit, no DB query

3239```

3240

3241Use when sequential user actions hit multiple endpoints needing the same data within seconds.

3242

3243**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.

3244

3245**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.

3246

3247Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

3248

3249

3250

3251## Per-Request Deduplication with React.cache()

3252

3253Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.

3254

3255**Usage:**

3256

3257```typescript

3258import { cache } from 'react'

3259

3260export const getCurrentUser = cache(async () => {

3261 const session = await auth()

3262 if (!session?.user?.id) return null

3263 return await db.user.findUnique({

3264 where: { id: session.user.id }

3265 })

3266})

3267```

3268

3269Within a single request, multiple calls to `getCurrentUser()` execute the query only once.

3270

3271**Avoid inline objects as arguments:**

3272

3273`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.

3274

3275**Incorrect (always cache miss):**

3276

3277```typescript

3278const getUser = cache(async (params: { uid: number }) => {

3279 return await db.user.findUnique({ where: { id: params.uid } })

3280})

3281

3282// Each call creates new object, never hits cache

3283getUser({ uid: 1 })

3284getUser({ uid: 1 }) // Cache miss, runs query again

3285```

3286

3287**Correct (cache hit):**

3288

3289```typescript

3290const getUser = cache(async (uid: number) => {

3291 return await db.user.findUnique({ where: { id: uid } })

3292})

3293

3294// Primitive args use value equality

3295getUser(1)

3296getUser(1) // Cache hit, returns cached result

3297```

3298

3299If you must pass objects, pass the same reference:

3300

3301```typescript

3302const params = { uid: 1 }

3303getUser(params) // Query runs

3304getUser(params) // Cache hit (same reference)

3305```

3306

3307**Next.js-Specific Note:**

3308

3309In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:

3310

3311- Database queries (Prisma, Drizzle, etc.)

3312- Heavy computations

3313- Authentication checks

3314- File system operations

3315- Any non-fetch async work

3316

3317Use `React.cache()` to deduplicate these operations across your component tree.

3318

3319Reference: [React.cache documentation](https://react.dev/reference/react/cache)

3320

3321

3322

3323## Avoid Duplicate Serialization in RSC Props

3324

3325**Impact: LOW (reduces network payload by avoiding duplicate serialization)**

3326

3327RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.

3328

3329**Incorrect (duplicates array):**

3330

3331```tsx

3332// RSC: sends 6 strings (2 arrays × 3 items)

3333<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />

3334```

3335

3336**Correct (sends 3 strings):**

3337

3338```tsx

3339// RSC: send once

3340<ClientList usernames={usernames} />

3341

3342// Client: transform there

3343'use client'

3344const sorted = useMemo(() => [...usernames].sort(), [usernames])

3345```

3346

3347**Nested deduplication behavior:**

3348

3349Deduplication works recursively. Impact varies by data type:

3350

3351- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated

3352- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference

3353

3354```tsx

3355// string[] - duplicates everything

3356usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings

3357

3358// object[] - duplicates array structure only

3359users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)

3360```

3361

3362**Operations breaking deduplication (create new references):**

3363

3364- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`

3365- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`

3366

3367**More examples:**

3368

3369```tsx

3370// ❌ Bad

3371<C users={users} active={users.filter(u => u.active)} />

3372<C product={product} productName={product.name} />

3373

3374// ✅ Good

3375<C users={users} />

3376<C product={product} />

3377// Do filtering/destructuring in client

3378```

3379

3380**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

3381

3382

3383

3384## Hoist Static I/O to Module Level

3385

3386**Impact: HIGH (avoids repeated file/network I/O per request)**

3387

3388When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.

3389

3390**Incorrect (reads font file on every request):**

3391

3392```typescript

3393// app/api/og/route.tsx

3394import { ImageResponse } from 'next/og'

3395

3396export async function GET(request: Request) {

3397 // Runs on EVERY request - expensive!

3398 const fontData = await fetch(

3399 new URL('./fonts/Inter.ttf', import.meta.url)

3400 ).then(res => res.arrayBuffer())

3401

3402 const logoData = await fetch(

3403 new URL('./images/logo.png', import.meta.url)

3404 ).then(res => res.arrayBuffer())

3405

3406 return new ImageResponse(

3407 <div style={{ fontFamily: 'Inter' }}>

3408 <img src={logoData} />

3409 Hello World

3410 </div>,

3411 { fonts: [{ name: 'Inter', data: fontData }] }

3412 )

3413}

3414```

3415

3416**Correct (loads once at module initialization):**

3417

3418```typescript

3419// app/api/og/route.tsx

3420import { ImageResponse } from 'next/og'

3421

3422// Module-level: runs ONCE when module is first imported

3423const fontData = fetch(

3424 new URL('./fonts/Inter.ttf', import.meta.url)

3425).then(res => res.arrayBuffer())

3426

3427const logoData = fetch(

3428 new URL('./images/logo.png', import.meta.url)

3429).then(res => res.arrayBuffer())

3430

3431export async function GET(request: Request) {

3432 // Await the already-started promises

3433 const [font, logo] = await Promise.all([fontData, logoData])

3434

3435 return new ImageResponse(

3436 <div style={{ fontFamily: 'Inter' }}>

3437 <img src={logo} />

3438 Hello World

3439 </div>,

3440 { fonts: [{ name: 'Inter', data: font }] }

3441 )

3442}

3443```

3444

3445**Correct (synchronous fs at module level):**

3446

3447```typescript

3448// app/api/og/route.tsx

3449import { ImageResponse } from 'next/og'

3450import { readFileSync } from 'fs'

3451import { join } from 'path'

3452

3453// Synchronous read at module level - blocks only during module init

3454const fontData = readFileSync(

3455 join(process.cwd(), 'public/fonts/Inter.ttf')

3456)

3457

3458const logoData = readFileSync(

3459 join(process.cwd(), 'public/images/logo.png')

3460)

3461

3462export async function GET(request: Request) {

3463 return new ImageResponse(

3464 <div style={{ fontFamily: 'Inter' }}>

3465 <img src={logoData} />

3466 Hello World

3467 </div>,

3468 { fonts: [{ name: 'Inter', data: fontData }] }

3469 )

3470}

3471```

3472

3473**Incorrect (reads config on every call):**

3474

3475```typescript

3476import fs from 'node:fs/promises'

3477

3478export async function processRequest(data: Data) {

3479 const config = JSON.parse(

3480 await fs.readFile('./config.json', 'utf-8')

3481 )

3482 const template = await fs.readFile('./template.html', 'utf-8')

3483

3484 return render(template, data, config)

3485}

3486```

3487

3488**Correct (hoists config and template to module level):**

3489

3490```typescript

3491import fs from 'node:fs/promises'

3492

3493const configPromise = fs

3494 .readFile('./config.json', 'utf-8')

3495 .then(JSON.parse)

3496const templatePromise = fs.readFile('./template.html', 'utf-8')

3497

3498export async function processRequest(data: Data) {

3499 const [config, template] = await Promise.all([

3500 configPromise,

3501 templatePromise,

3502 ])

3503

3504 return render(template, data, config)

3505}

3506```

3507

3508When to use this pattern:

3509

3510- Loading fonts for OG image generation

3511- Loading static logos, icons, or watermarks

3512- Reading configuration files that don't change at runtime

3513- Loading email templates or other static templates

3514- Any static asset that's the same across all requests

3515

3516When not to use this pattern:

3517

3518- Assets that vary per request or user

3519- Files that may change during runtime (use caching with TTL instead)

3520- Large files that would consume too much memory if kept loaded

3521- Sensitive data that shouldn't persist in memory

3522

3523With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.

3524

3525In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.

3526

3527

3528

3529## Avoid Shared Module State for Request Data

3530

3531For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.

3532

3533Treat module scope on the server as process-wide shared memory, not request-local state.

3534

3535**Incorrect (request data leaks across concurrent renders):**

3536

3537```tsx

3538let currentUser: User | null = null

3539

3540export default async function Page() {

3541 currentUser = await auth()

3542 return <Dashboard />

3543}

3544

3545async function Dashboard() {

3546 return <div>{currentUser?.name}</div>

3547}

3548```

3549

3550If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.

3551

3552**Correct (keep request data local to the render tree):**

3553

3554```tsx

3555export default async function Page() {

3556 const user = await auth()

3557 return <Dashboard user={user} />

3558}

3559

3560function Dashboard({ user }: { user: User | null }) {

3561 return <div>{user?.name}</div>

3562}

3563```

3564

3565Safe exceptions:

3566

3567- Immutable static assets or config loaded once at module scope

3568- Shared caches intentionally designed for cross-request reuse and keyed correctly

3569- Process-wide singletons that do not store request- or user-specific mutable data

3570

3571For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).

3572

3573

3574

3575## Parallel Data Fetching with Component Composition

3576

3577React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.

3578

3579**Incorrect (Sidebar waits for Page's fetch to complete):**

3580

3581```tsx

3582export default async function Page() {

3583 const header = await fetchHeader()

3584 return (

3585 <div>

3586 <div>{header}</div>

3587 <Sidebar />

3588 </div>

3589 )

3590}

3591

3592async function Sidebar() {

3593 const items = await fetchSidebarItems()

3594 return <nav>{items.map(renderItem)}</nav>

3595}

3596```

3597

3598**Correct (both fetch simultaneously):**

3599

3600```tsx

3601async function Header() {

3602 const data = await fetchHeader()

3603 return <div>{data}</div>

3604}

3605

3606async function Sidebar() {

3607 const items = await fetchSidebarItems()

3608 return <nav>{items.map(renderItem)}</nav>

3609}

3610

3611export default function Page() {

3612 return (

3613 <div>

3614 <Header />

3615 <Sidebar />

3616 </div>

3617 )

3618}

3619```

3620

3621**Alternative with children prop:**

3622

3623```tsx

3624async function Header() {

3625 const data = await fetchHeader()

3626 return <div>{data}</div>

3627}

3628

3629async function Sidebar() {

3630 const items = await fetchSidebarItems()

3631 return <nav>{items.map(renderItem)}</nav>

3632}

3633

3634function Layout({ children }: { children: ReactNode }) {

3635 return (

3636 <div>

3637 <Header />

3638 {children}

3639 </div>

3640 )

3641}

3642

3643export default function Page() {

3644 return (

3645 <Layout>

3646 <Sidebar />

3647 </Layout>

3648 )

3649}

3650```

3651

3652

3653

3654## Parallel Nested Data Fetching

3655

3656When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.

3657

3658**Incorrect (a single slow item blocks all nested fetches):**

3659

3660```tsx

3661const chats = await Promise.all(

3662 chatIds.map(id => getChat(id))

3663)

3664

3665const chatAuthors = await Promise.all(

3666 chats.map(chat => getUser(chat.author))

3667)

3668```

3669

3670If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.

3671

3672**Correct (each item chains its own nested fetch):**

3673

3674```tsx

3675const chatAuthors = await Promise.all(

3676 chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))

3677)

3678```

3679

3680Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.

3681

3682

3683

3684## Minimize Serialization at RSC Boundaries

3685

3686The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.

3687

3688**Incorrect (serializes all 50 fields):**

3689

3690```tsx

3691async function Page() {

3692 const user = await fetchUser() // 50 fields

3693 return <Profile user={user} />

3694}

3695

3696'use client'

3697function Profile({ user }: { user: User }) {

3698 return <div>{user.name}</div> // uses 1 field

3699}

3700```

3701

3702**Correct (serializes only 1 field):**

3703

3704```tsx

3705async function Page() {

3706 const user = await fetchUser()

3707 return <Profile name={user.name} />

3708}

3709

3710'use client'

3711function Profile({ name }: { name: string }) {

3712 return <div>{name}</div>

3713}

3714```

3715

3716

The other instruction files in this repository
Repository	Format	Stack	Covers	Score	Changed
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-build.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-code-simplify.mdc · 51	Cursor rules	typescriptgithub-actions	testing-strategy	30/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-plan.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-review.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-ship.mdc · 51	Cursor rules	typescriptgithub-actions	testing-strategygitdeploymentdo-not	61/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-spec.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-test.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/AGENTS.md · 51	AGENTS.md	typescriptgithub-actions	lint-formatstylearchdo-not	73/100	today
nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/CLAUDE.md · 51	CLAUDE.md	typescriptgithub-actions	teststylearchagent-behaviour	70/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-cancel-ralph.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	16/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-help.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	54/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-ralph-loop.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	22/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_agent-sdk-dev/for-cursor/.cursor/rules/cmd-new-sdk-app.mdc · 51	Cursor rules	typescriptgithub-actions	setupstylearchdocs	76/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_claude-md-management/for-cursor/.cursor/rules/cmd-revise-claude-md.mdc · 51	Cursor rules	typescriptgithub-actions	agent-behaviour	50/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_code-review/for-cursor/.cursor/rules/cmd-code-review.mdc · 51	Cursor rules	typescriptgithub-actions	testing-strategygit	35/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-clean_gone.mdc · 51	Cursor rules	typescriptgithub-actions	no sections	60/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit-push-pr.mdc · 51	Cursor rules	typescriptgithub-actions	stylegit	44/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit.mdc · 51	Cursor rules	typescriptgithub-actions	style	44/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_example-plugin/for-cursor/.cursor/rules/cmd-example-command.mdc · 51	Cursor rules	typescriptgithub-actions	lint-formatstyleagent-behaviour	58/100	today
nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_feature-dev/for-cursor/.cursor/rules/cmd-feature-dev.mdc · 51	Cursor rules	typescriptgithub-actions	stylearchgit	56/100	today

The other instruction files in this repository

Repository

Format

Stack

Covers

Score

Changed

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-build.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-code-simplify.mdc · 51

Cursor rules

typescriptgithub-actions

testing-strategy

30/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-plan.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-review.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-ship.mdc · 51

Cursor rules

typescriptgithub-actions

testing-strategygitdeploymentdo-not

61/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-spec.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-cursor/.cursor/rules/cmd-test.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/AGENTS.md · 51

AGENTS.md

typescriptgithub-actions

lint-formatstylearchdo-not

73/100

today

nota-america/forgecat-agent-profilesprofiles/addyosmani/agent-skills/for-forgecat/CLAUDE.md · 51

CLAUDE.md

typescriptgithub-actions

teststylearchagent-behaviour

70/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-cancel-ralph.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

16/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-help.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

54/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-code/anthropics_claude-code_ralph-wiggum/for-cursor/.cursor/rules/cmd-ralph-loop.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

22/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_agent-sdk-dev/for-cursor/.cursor/rules/cmd-new-sdk-app.mdc · 51

Cursor rules

typescriptgithub-actions

setupstylearchdocs

76/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_claude-md-management/for-cursor/.cursor/rules/cmd-revise-claude-md.mdc · 51

Cursor rules

typescriptgithub-actions

agent-behaviour

50/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_code-review/for-cursor/.cursor/rules/cmd-code-review.mdc · 51

Cursor rules

typescriptgithub-actions

testing-strategygit

35/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-clean_gone.mdc · 51

Cursor rules

typescriptgithub-actions

no sections

60/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit-push-pr.mdc · 51

Cursor rules

typescriptgithub-actions

stylegit

44/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_commit-commands/for-cursor/.cursor/rules/cmd-commit.mdc · 51

Cursor rules

typescriptgithub-actions

style

44/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_example-plugin/for-cursor/.cursor/rules/cmd-example-command.mdc · 51

Cursor rules

typescriptgithub-actions

lint-formatstyleagent-behaviour

58/100

today

nota-america/forgecat-agent-profilesprofiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_feature-dev/for-cursor/.cursor/rules/cmd-feature-dev.mdc · 51

Cursor rules

typescriptgithub-actions

stylearchgit

56/100

today

Repository	Format	Stack	Covers	Score	Changed
vllm-project/vllmAGENTS.md · 89k	AGENTS.md	pythonpytorch+3	setuptestlint-formatstyle+5	100/100	14 days ago
code-yeongyu/oh-my-openagentpackages/web/AGENTS.md · 68k	AGENTS.md	typescriptbun+10	setupbuildtestlint-format+6	100/100	13 days ago
deepseek-ai/deepseek-harnessnative/landlock-run/AGENTS.md · 104k	AGENTS.md	typescriptvitest+9	setupteststylearch+3	100/100	today
TryGhost/Ghoste2e/AGENTS.md · 55k	AGENTS.md	typescriptjavascript+11	setupteststylearch+2	100/100	today
aaif-goose/gooseAGENTS.md · 53k	AGENTS.md	rusttypescript+2	setupbuildtestlint-format+7	100/100	8 days ago
duckduckgo/content-scope-scriptsspecial-pages/AGENTS.md · 70	AGENTS.md	typescriptjavascript+5	buildteststylearch+3	100/100	14 days ago
n8n-io/n8npackages/@n8n/agents/AGENTS.md · 201k	AGENTS.md	typescriptlangchain+16	buildteststylearch+3	100/100	14 days ago
mui/material-uiAGENTS.md · 99k	AGENTS.md	typescriptjavascript+13	setupbuildtestlint-format+9	100/100	14 days ago

Built for the same person as RuleStack

Built for the same person as RuleStack

Also in nota-america/forgecat-agent-profiles

Similar configs

Put this measurement in your README