\n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct: wrapper shows immediately, data streams in**\n\n```tsx\nfunction Page() {\n return (\n Sidebar
\n Header
\n \n
\n Footer
\n \n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return Sidebar
\n Header
\n \n
\n Footer
\n {data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative: share promise across components**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n \n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return Sidebar
\n Header
\n Footer
\n {data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return {data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n\n- SEO-critical content above the fold\n\n- Small, fast queries where suspense overhead isn't worth it\n\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n\n---\n\n## 2. Bundle Size Optimization\n\n**Impact: CRITICAL**\n\nReducing initial bundle size improves Time to Interactive and Largest Contentful Paint.\n\n### 2.1 Avoid Barrel File Imports\n\n**Impact: CRITICAL (200-800ms import cost, slow builds)**\n\nImport 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'`).\n\nPopular 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.\n\n**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.\n\n**Incorrect: imports entire library**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct - Next.js 13.5+ (recommended):**\n\n```tsx\n// Keep the standard imports - Next.js transforms them to direct imports\nimport { Check, X, Menu } from 'lucide-react'\n// Full TypeScript support, no manual path wrangling\n```\n\nThis is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.\n\n**Correct - Direct imports (non-Next.js projects):**\n\n```tsx\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n> **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.\n\nThese optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries 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`.\n\nReference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n\n### 2.2 Conditional Module Loading\n\n**Impact: HIGH (loads large data only when needed)**\n\nLoad large data or modules only when a feature is activated.\n\n**Example: lazy-load animation frames**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch{currentUser?.name}
\n}\n```\n\nIf two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.\n\n**Correct: keep request data local to the render tree**\n\n```tsx\nexport default async function Page() {\n const user = await auth()\n return {user?.name}
\n}\n```\n\nSafe exceptions:\n\n- Immutable static assets or config loaded once at module scope\n\n- Shared caches intentionally designed for cross-request reuse and keyed correctly\n\n- Process-wide singletons that do not store request- or user-specific mutable data\n\nFor static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).\n\n### 3.4 Cross-Request LRU Caching\n\n**Impact: HIGH (caches across requests)**\n\n`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.\n\n**Implementation:**\n\n```typescript\nimport { LRUCache } from 'lru-cache'\n\nconst cache = new LRUCache\n 
\n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Correct: loads once at module initialization**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\n\n// Module-level: runs ONCE when module is first imported\nconst fontData = fetch(\n new URL('./fonts/Inter.ttf', import.meta.url)\n).then(res => res.arrayBuffer())\n\nconst logoData = fetch(\n new URL('./images/logo.png', import.meta.url)\n).then(res => res.arrayBuffer())\n\nexport async function GET(request: Request) {\n // Await the already-started promises\n const [font, logo] = await Promise.all([fontData, logoData])\n\n return new ImageResponse(\n \n 
\n Hello World\n
,\n { fonts: [{ name: 'Inter', data: font }] }\n )\n}\n```\n\n**Correct: synchronous fs at module level**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\nimport { readFileSync } from 'fs'\nimport { join } from 'path'\n\n// Synchronous read at module level - blocks only during module init\nconst fontData = readFileSync(\n join(process.cwd(), 'public/fonts/Inter.ttf')\n)\n\nconst logoData = readFileSync(\n join(process.cwd(), 'public/images/logo.png')\n)\n\nexport async function GET(request: Request) {\n return new ImageResponse(\n \n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Incorrect: reads config on every call**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nexport async function processRequest(data: Data) {\n const config = JSON.parse(\n await fs.readFile('./config.json', 'utf-8')\n )\n const template = await fs.readFile('./template.html', 'utf-8')\n\n return render(template, data, config)\n}\n```\n\n**Correct: hoists config and template to module level**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nconst configPromise = fs\n .readFile('./config.json', 'utf-8')\n .then(JSON.parse)\nconst templatePromise = fs.readFile('./template.html', 'utf-8')\n\nexport async function processRequest(data: Data) {\n const [config, template] = await Promise.all([\n configPromise,\n templatePromise,\n ])\n\n return render(template, data, config)\n}\n```\n\nWhen to use this pattern:\n\n- Loading fonts for OG image generation\n\n- Loading static logos, icons, or watermarks\n\n- Reading configuration files that don't change at runtime\n\n- Loading email templates or other static templates\n\n- Any static asset that's the same across all requests\n\nWhen not to use this pattern:\n\n- Assets that vary per request or user\n\n- Files that may change during runtime (use caching with TTL instead)\n\n- Large files that would consume too much memory if kept loaded\n\n- Sensitive data that shouldn't persist in memory\n\nWith 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.\n\nIn traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.\n\n### 3.6 Minimize Serialization at RSC Boundaries\n\n**Impact: HIGH (reduces data transfer size)**\n\nThe 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.\n\n**Incorrect: serializes all 50 fields**\n\n```tsx\nasync function Page() {\n const user = await fetchUser() // 50 fields\n return {user.name}
// uses 1 field\n}\n```\n\n**Correct: serializes only 1 field**\n\n```tsx\nasync function Page() {\n const user = await fetchUser()\n return {name}
\n}\n```\n\n### 3.7 Parallel Data Fetching with Component Composition\n\n**Impact: CRITICAL (eliminates server-side waterfalls)**\n\nReact Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.\n\n**Incorrect: Sidebar waits for Page's fetch to complete**\n\n```tsx\nexport default async function Page() {\n const header = await fetchHeader()\n return (\n \n
\n )\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n```\n\n**Correct: both fetch simultaneously**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {header}
\n {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nexport default function Page() {\n return (\n \n
\n )\n}\n```\n\n**Alternative with children prop:**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nfunction Layout({ children }: { children: ReactNode }) {\n return (\n \n
\n )\n}\n\nexport default function Page() {\n return (\n \n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct (wrapper shows immediately, data streams in):**\n\n```tsx\nfunction Page() {\n return (\n Sidebar
\n Header
\n \n
\n Footer
\n \n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return Sidebar
\n Header
\n \n
\n Footer
\n {data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative (share promise across components):**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n \n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return Sidebar
\n Header
\n Footer
\n {data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return {data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n- SEO-critical content above the fold\n- Small, fast queries where suspense overhead isn't worth it\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n","skills/react-best-practices/rules/bundle-analyzable-paths.md":"---\ntitle: Prefer Statically Analyzable Paths\nimpact: HIGH\nimpactDescription: avoids accidental broad bundles and file traces\ntags: bundle, nextjs, vite, webpack, rollup, esbuild, path\n---\n\n## Prefer Statically Analyzable Paths\n\nBuild 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.\n\nPrefer 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.\n\nWhen analysis becomes too broad, the cost is real:\n- Larger server bundles\n- Slower builds\n- Worse cold starts\n- More memory use\n\n### Import Paths\n\n**Incorrect (the bundler cannot tell what may be imported):**\n\n```ts\nconst PAGE_MODULES = {\n home: './pages/home',\n settings: './pages/settings',\n} as const\n\nconst Page = await import(PAGE_MODULES[pageName])\n```\n\n**Correct (use an explicit map of allowed modules):**\n\n```ts\nconst PAGE_MODULES = {\n home: () => import('./pages/home'),\n settings: () => import('./pages/settings'),\n} as const\n\nconst Page = await PAGE_MODULES[pageName]()\n```\n\n### File-System Paths\n\n**Incorrect (a 2-value enum still hides the final path from static analysis):**\n\n```ts\nconst baseDir = path.join(process.cwd(), 'content/' + contentKind)\n```\n\n**Correct (make each final path literal at the callsite):**\n\n```ts\nconst baseDir =\n kind === ContentKind.Blog\n ? path.join(process.cwd(), 'content/blog')\n : path.join(process.cwd(), 'content/docs')\n```\n\nIn 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.\n\nReference: [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/)\n","skills/react-best-practices/rules/bundle-barrel-imports.md":"---\ntitle: Avoid Barrel File Imports\nimpact: CRITICAL\nimpactDescription: 200-800ms import cost, slow builds\ntags: bundle, imports, tree-shaking, barrel-files, performance\n---\n\n## Avoid Barrel File Imports\n\nImport 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'`).\n\nPopular 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.\n\n**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.\n\n**Incorrect (imports entire library):**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct - Next.js 13.5+ (recommended):**\n\n```js\n// next.config.js - automatically optimizes barrel imports at build time\nmodule.exports = {\n experimental: {\n optimizePackageImports: ['lucide-react', '@mui/material']\n }\n}\n```\n\n```tsx\n// Keep the standard imports - Next.js transforms them to direct imports\nimport { Check, X, Menu } from 'lucide-react'\n// Full TypeScript support, no manual path wrangling\n```\n\nThis is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.\n\n**Correct - Direct imports (non-Next.js projects):**\n\n```tsx\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n> **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.\n\nThese optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries 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`.\n\nReference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n","skills/react-best-practices/rules/bundle-conditional.md":"---\ntitle: Conditional Module Loading\nimpact: HIGH\nimpactDescription: loads large data only when needed\ntags: bundle, conditional-loading, lazy-loading\n---\n\n## Conditional Module Loading\n\nLoad large data or modules only when a feature is activated.\n\n**Example (lazy-load animation frames):**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.DispatchContent
\n}\n\n// Correct: toggle class\nfunction Box({ isHighlighted }: { isHighlighted: boolean }) {\n return (\n \n Content\n
\n )\n}\n```\n\nPrefer 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.\n\nSee [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.\n","skills/react-best-practices/rules/js-cache-function-results.md":"---\ntitle: Cache Repeated Function Calls\nimpact: MEDIUM\nimpactDescription: avoid redundant computation\ntags: javascript, cache, memoization, performance\n---\n\n## Cache Repeated Function Calls\n\nUse a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.\n\n**Incorrect (redundant computation):**\n\n```typescript\nfunction ProjectList({ projects }: { projects: Project[] }) {\n return (\n \n {projects.map(project => {\n // slugify() called 100+ times for same project names\n const slug = slugify(project.name)\n \n return
\n )\n}\n```\n\n**Correct (cached results):**\n\n```typescript\n// Module-level cache\nconst slugifyCache = new Map\n {projects.map(project => {\n // Computed only once per unique project name\n const slug = cachedSlugify(project.name)\n \n return
\n )\n}\n```\n\n**Simpler pattern for single-value functions:**\n\n```typescript\nlet isLoggedInCache: boolean | null = null\n\nfunction isLoggedIn(): boolean {\n if (isLoggedInCache !== null) {\n return isLoggedInCache\n }\n \n isLoggedInCache = document.cookie.includes('auth=')\n return isLoggedInCache\n}\n\n// Clear cache when auth changes\nfunction onAuthChange() {\n isLoggedInCache = null\n}\n```\n\nUse a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.\n\nReference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)\n","skills/react-best-practices/rules/js-cache-property-access.md":"---\ntitle: Cache Property Access in Loops\nimpact: LOW-MEDIUM\nimpactDescription: reduces lookups\ntags: javascript, loops, optimization, caching\n---\n\n## Cache Property Access in Loops\n\nCache object property lookups in hot paths.\n\n**Incorrect (3 lookups × N iterations):**\n\n```typescript\nfor (let i = 0; i < arr.length; i++) {\n process(obj.config.settings.value)\n}\n```\n\n**Correct (1 lookup total):**\n\n```typescript\nconst value = obj.config.settings.value\nconst len = arr.length\nfor (let i = 0; i < len; i++) {\n process(value)\n}\n```\n","skills/react-best-practices/rules/js-cache-storage.md":"---\ntitle: Cache Storage API Calls\nimpact: LOW-MEDIUM\nimpactDescription: reduces expensive I/O\ntags: javascript, localStorage, storage, caching, performance\n---\n\n## Cache Storage API Calls\n\n`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.\n\n**Incorrect (reads storage on every call):**\n\n```typescript\nfunction getTheme() {\n return localStorage.getItem('theme') ?? 'light'\n}\n// Called 10 times = 10 storage reads\n```\n\n**Correct (Map cache):**\n\n```typescript\nconst storageCache = new Map\n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct: wrapper shows immediately, data streams in**\n\n```tsx\nfunction Page() {\n return (\n Sidebar
\n Header
\n \n
\n Footer
\n \n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return Sidebar
\n Header
\n \n
\n Footer
\n {data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative: share promise across components**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n \n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return Sidebar
\n Header
\n Footer
\n {data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return {data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n\n- SEO-critical content above the fold\n\n- Small, fast queries where suspense overhead isn't worth it\n\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n\n---\n\n## 2. Bundle Size Optimization\n\n**Impact: CRITICAL**\n\nReducing initial bundle size improves Time to Interactive and Largest Contentful Paint.\n\n### 2.1 Avoid Barrel File Imports\n\n**Impact: CRITICAL (200-800ms import cost, slow builds)**\n\nImport 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'`).\n\nPopular 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.\n\n**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.\n\n**Incorrect: imports entire library**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct - Next.js 13.5+ (recommended):**\n\n```tsx\n// Keep the standard imports - Next.js transforms them to direct imports\nimport { Check, X, Menu } from 'lucide-react'\n// Full TypeScript support, no manual path wrangling\n```\n\nThis is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.\n\n**Correct - Direct imports (non-Next.js projects):**\n\n```tsx\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n> **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.\n\nThese optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries 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`.\n\nReference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n\n### 2.2 Conditional Module Loading\n\n**Impact: HIGH (loads large data only when needed)**\n\nLoad large data or modules only when a feature is activated.\n\n**Example: lazy-load animation frames**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch{currentUser?.name}
\n}\n```\n\nIf two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.\n\n**Correct: keep request data local to the render tree**\n\n```tsx\nexport default async function Page() {\n const user = await auth()\n return {user?.name}
\n}\n```\n\nSafe exceptions:\n\n- Immutable static assets or config loaded once at module scope\n\n- Shared caches intentionally designed for cross-request reuse and keyed correctly\n\n- Process-wide singletons that do not store request- or user-specific mutable data\n\nFor static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).\n\n### 3.4 Cross-Request LRU Caching\n\n**Impact: HIGH (caches across requests)**\n\n`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.\n\n**Implementation:**\n\n```typescript\nimport { LRUCache } from 'lru-cache'\n\nconst cache = new LRUCache\n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Correct: loads once at module initialization**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\n\n// Module-level: runs ONCE when module is first imported\nconst fontData = fetch(\n new URL('./fonts/Inter.ttf', import.meta.url)\n).then(res => res.arrayBuffer())\n\nconst logoData = fetch(\n new URL('./images/logo.png', import.meta.url)\n).then(res => res.arrayBuffer())\n\nexport async function GET(request: Request) {\n // Await the already-started promises\n const [font, logo] = await Promise.all([fontData, logoData])\n\n return new ImageResponse(\n \n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: font }] }\n )\n}\n```\n\n**Correct: synchronous fs at module level**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\nimport { readFileSync } from 'fs'\nimport { join } from 'path'\n\n// Synchronous read at module level - blocks only during module init\nconst fontData = readFileSync(\n join(process.cwd(), 'public/fonts/Inter.ttf')\n)\n\nconst logoData = readFileSync(\n join(process.cwd(), 'public/images/logo.png')\n)\n\nexport async function GET(request: Request) {\n return new ImageResponse(\n \n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Incorrect: reads config on every call**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nexport async function processRequest(data: Data) {\n const config = JSON.parse(\n await fs.readFile('./config.json', 'utf-8')\n )\n const template = await fs.readFile('./template.html', 'utf-8')\n\n return render(template, data, config)\n}\n```\n\n**Correct: hoists config and template to module level**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nconst configPromise = fs\n .readFile('./config.json', 'utf-8')\n .then(JSON.parse)\nconst templatePromise = fs.readFile('./template.html', 'utf-8')\n\nexport async function processRequest(data: Data) {\n const [config, template] = await Promise.all([\n configPromise,\n templatePromise,\n ])\n\n return render(template, data, config)\n}\n```\n\nWhen to use this pattern:\n\n- Loading fonts for OG image generation\n\n- Loading static logos, icons, or watermarks\n\n- Reading configuration files that don't change at runtime\n\n- Loading email templates or other static templates\n\n- Any static asset that's the same across all requests\n\nWhen not to use this pattern:\n\n- Assets that vary per request or user\n\n- Files that may change during runtime (use caching with TTL instead)\n\n- Large files that would consume too much memory if kept loaded\n\n- Sensitive data that shouldn't persist in memory\n\nWith 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.\n\nIn traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.\n\n### 3.6 Minimize Serialization at RSC Boundaries\n\n**Impact: HIGH (reduces data transfer size)**\n\nThe 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.\n\n**Incorrect: serializes all 50 fields**\n\n```tsx\nasync function Page() {\n const user = await fetchUser() // 50 fields\n return {user.name}
// uses 1 field\n}\n```\n\n**Correct: serializes only 1 field**\n\n```tsx\nasync function Page() {\n const user = await fetchUser()\n return {name}
\n}\n```\n\n### 3.7 Parallel Data Fetching with Component Composition\n\n**Impact: CRITICAL (eliminates server-side waterfalls)**\n\nReact Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.\n\n**Incorrect: Sidebar waits for Page's fetch to complete**\n\n```tsx\nexport default async function Page() {\n const header = await fetchHeader()\n return (\n \n
\n )\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n```\n\n**Correct: both fetch simultaneously**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {header}
\n {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nexport default function Page() {\n return (\n \n
\n )\n}\n```\n\n**Alternative with children prop:**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nfunction Layout({ children }: { children: ReactNode }) {\n return (\n \n
\n )\n}\n\nexport default function Page() {\n return (\n \n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct (wrapper shows immediately, data streams in):**\n\n```tsx\nfunction Page() {\n return (\n Sidebar
\n Header
\n \n
\n Footer
\n \n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return Sidebar
\n Header
\n \n
\n Footer
\n {data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative (share promise across components):**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n \n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return Sidebar
\n Header
\n Footer
\n {data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return {data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n- SEO-critical content above the fold\n- Small, fast queries where suspense overhead isn't worth it\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n","skills/react-best-practices/rules/bundle-analyzable-paths.md":"---\ntitle: Prefer Statically Analyzable Paths\nimpact: HIGH\nimpactDescription: avoids accidental broad bundles and file traces\ntags: bundle, nextjs, vite, webpack, rollup, esbuild, path\n---\n\n## Prefer Statically Analyzable Paths\n\nBuild 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.\n\nPrefer 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.\n\nWhen analysis becomes too broad, the cost is real:\n- Larger server bundles\n- Slower builds\n- Worse cold starts\n- More memory use\n\n### Import Paths\n\n**Incorrect (the bundler cannot tell what may be imported):**\n\n```ts\nconst PAGE_MODULES = {\n home: './pages/home',\n settings: './pages/settings',\n} as const\n\nconst Page = await import(PAGE_MODULES[pageName])\n```\n\n**Correct (use an explicit map of allowed modules):**\n\n```ts\nconst PAGE_MODULES = {\n home: () => import('./pages/home'),\n settings: () => import('./pages/settings'),\n} as const\n\nconst Page = await PAGE_MODULES[pageName]()\n```\n\n### File-System Paths\n\n**Incorrect (a 2-value enum still hides the final path from static analysis):**\n\n```ts\nconst baseDir = path.join(process.cwd(), 'content/' + contentKind)\n```\n\n**Correct (make each final path literal at the callsite):**\n\n```ts\nconst baseDir =\n kind === ContentKind.Blog\n ? path.join(process.cwd(), 'content/blog')\n : path.join(process.cwd(), 'content/docs')\n```\n\nIn 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.\n\nReference: [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/)\n","skills/react-best-practices/rules/bundle-barrel-imports.md":"---\ntitle: Avoid Barrel File Imports\nimpact: CRITICAL\nimpactDescription: 200-800ms import cost, slow builds\ntags: bundle, imports, tree-shaking, barrel-files, performance\n---\n\n## Avoid Barrel File Imports\n\nImport 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'`).\n\nPopular 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.\n\n**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.\n\n**Incorrect (imports entire library):**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct - Next.js 13.5+ (recommended):**\n\n```js\n// next.config.js - automatically optimizes barrel imports at build time\nmodule.exports = {\n experimental: {\n optimizePackageImports: ['lucide-react', '@mui/material']\n }\n}\n```\n\n```tsx\n// Keep the standard imports - Next.js transforms them to direct imports\nimport { Check, X, Menu } from 'lucide-react'\n// Full TypeScript support, no manual path wrangling\n```\n\nThis is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.\n\n**Correct - Direct imports (non-Next.js projects):**\n\n```tsx\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n> **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.\n\nThese optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries 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`.\n\nReference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n","skills/react-best-practices/rules/bundle-conditional.md":"---\ntitle: Conditional Module Loading\nimpact: HIGH\nimpactDescription: loads large data only when needed\ntags: bundle, conditional-loading, lazy-loading\n---\n\n## Conditional Module Loading\n\nLoad large data or modules only when a feature is activated.\n\n**Example (lazy-load animation frames):**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.DispatchContent
\n}\n\n// Correct: toggle class\nfunction Box({ isHighlighted }: { isHighlighted: boolean }) {\n return (\n \n Content\n
\n )\n}\n```\n\nPrefer 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.\n\nSee [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.\n","skills/react-best-practices/rules/js-cache-function-results.md":"---\ntitle: Cache Repeated Function Calls\nimpact: MEDIUM\nimpactDescription: avoid redundant computation\ntags: javascript, cache, memoization, performance\n---\n\n## Cache Repeated Function Calls\n\nUse a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.\n\n**Incorrect (redundant computation):**\n\n```typescript\nfunction ProjectList({ projects }: { projects: Project[] }) {\n return (\n \n {projects.map(project => {\n // slugify() called 100+ times for same project names\n const slug = slugify(project.name)\n \n return
\n )\n}\n```\n\n**Correct (cached results):**\n\n```typescript\n// Module-level cache\nconst slugifyCache = new Map\n {projects.map(project => {\n // Computed only once per unique project name\n const slug = cachedSlugify(project.name)\n \n return
\n )\n}\n```\n\n**Simpler pattern for single-value functions:**\n\n```typescript\nlet isLoggedInCache: boolean | null = null\n\nfunction isLoggedIn(): boolean {\n if (isLoggedInCache !== null) {\n return isLoggedInCache\n }\n \n isLoggedInCache = document.cookie.includes('auth=')\n return isLoggedInCache\n}\n\n// Clear cache when auth changes\nfunction onAuthChange() {\n isLoggedInCache = null\n}\n```\n\nUse a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.\n\nReference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)\n","skills/react-best-practices/rules/js-cache-property-access.md":"---\ntitle: Cache Property Access in Loops\nimpact: LOW-MEDIUM\nimpactDescription: reduces lookups\ntags: javascript, loops, optimization, caching\n---\n\n## Cache Property Access in Loops\n\nCache object property lookups in hot paths.\n\n**Incorrect (3 lookups × N iterations):**\n\n```typescript\nfor (let i = 0; i < arr.length; i++) {\n process(obj.config.settings.value)\n}\n```\n\n**Correct (1 lookup total):**\n\n```typescript\nconst value = obj.config.settings.value\nconst len = arr.length\nfor (let i = 0; i < len; i++) {\n process(value)\n}\n```\n","skills/react-best-practices/rules/js-cache-storage.md":"---\ntitle: Cache Storage API Calls\nimpact: LOW-MEDIUM\nimpactDescription: reduces expensive I/O\ntags: javascript, localStorage, storage, caching, performance\n---\n\n## Cache Storage API Calls\n\n`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.\n\n**Incorrect (reads storage on every call):**\n\n```typescript\nfunction getTheme() {\n return localStorage.getItem('theme') ?? 'light'\n}\n// Called 10 times = 10 storage reads\n```\n\n**Correct (Map cache):**\n\n```typescript\nconst storageCache = new Map\n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct: wrapper shows immediately, data streams in**\n\n```tsx\nfunction Page() {\n return (\n Sidebar
\n Header
\n \n
\n Footer
\n \n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return Sidebar
\n Header
\n \n
\n Footer
\n {data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative: share promise across components**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n \n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return Sidebar
\n Header
\n Footer
\n {data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return {data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n\n- SEO-critical content above the fold\n\n- Small, fast queries where suspense overhead isn't worth it\n\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n\n---\n\n## 2. Bundle Size Optimization\n\n**Impact: CRITICAL**\n\nReducing initial bundle size improves Time to Interactive and Largest Contentful Paint.\n\n### 2.1 Avoid Barrel File Imports\n\n**Impact: CRITICAL (200-800ms import cost, slow builds)**\n\nImport 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'`).\n\nPopular 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.\n\n**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.\n\n**Incorrect: imports entire library**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct - Next.js 13.5+ (recommended):**\n\n```tsx\n// Keep the standard imports - Next.js transforms them to direct imports\nimport { Check, X, Menu } from 'lucide-react'\n// Full TypeScript support, no manual path wrangling\n```\n\nThis is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.\n\n**Correct - Direct imports (non-Next.js projects):**\n\n```tsx\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n> **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.\n\nThese optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries 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`.\n\nReference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n\n### 2.2 Conditional Module Loading\n\n**Impact: HIGH (loads large data only when needed)**\n\nLoad large data or modules only when a feature is activated.\n\n**Example: lazy-load animation frames**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch{currentUser?.name}
\n}\n```\n\nIf two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.\n\n**Correct: keep request data local to the render tree**\n\n```tsx\nexport default async function Page() {\n const user = await auth()\n return {user?.name}
\n}\n```\n\nSafe exceptions:\n\n- Immutable static assets or config loaded once at module scope\n\n- Shared caches intentionally designed for cross-request reuse and keyed correctly\n\n- Process-wide singletons that do not store request- or user-specific mutable data\n\nFor static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).\n\n### 3.4 Cross-Request LRU Caching\n\n**Impact: HIGH (caches across requests)**\n\n`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.\n\n**Implementation:**\n\n```typescript\nimport { LRUCache } from 'lru-cache'\n\nconst cache = new LRUCache\n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Correct: loads once at module initialization**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\n\n// Module-level: runs ONCE when module is first imported\nconst fontData = fetch(\n new URL('./fonts/Inter.ttf', import.meta.url)\n).then(res => res.arrayBuffer())\n\nconst logoData = fetch(\n new URL('./images/logo.png', import.meta.url)\n).then(res => res.arrayBuffer())\n\nexport async function GET(request: Request) {\n // Await the already-started promises\n const [font, logo] = await Promise.all([fontData, logoData])\n\n return new ImageResponse(\n \n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: font }] }\n )\n}\n```\n\n**Correct: synchronous fs at module level**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\nimport { readFileSync } from 'fs'\nimport { join } from 'path'\n\n// Synchronous read at module level - blocks only during module init\nconst fontData = readFileSync(\n join(process.cwd(), 'public/fonts/Inter.ttf')\n)\n\nconst logoData = readFileSync(\n join(process.cwd(), 'public/images/logo.png')\n)\n\nexport async function GET(request: Request) {\n return new ImageResponse(\n \n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Incorrect: reads config on every call**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nexport async function processRequest(data: Data) {\n const config = JSON.parse(\n await fs.readFile('./config.json', 'utf-8')\n )\n const template = await fs.readFile('./template.html', 'utf-8')\n\n return render(template, data, config)\n}\n```\n\n**Correct: hoists config and template to module level**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nconst configPromise = fs\n .readFile('./config.json', 'utf-8')\n .then(JSON.parse)\nconst templatePromise = fs.readFile('./template.html', 'utf-8')\n\nexport async function processRequest(data: Data) {\n const [config, template] = await Promise.all([\n configPromise,\n templatePromise,\n ])\n\n return render(template, data, config)\n}\n```\n\nWhen to use this pattern:\n\n- Loading fonts for OG image generation\n\n- Loading static logos, icons, or watermarks\n\n- Reading configuration files that don't change at runtime\n\n- Loading email templates or other static templates\n\n- Any static asset that's the same across all requests\n\nWhen not to use this pattern:\n\n- Assets that vary per request or user\n\n- Files that may change during runtime (use caching with TTL instead)\n\n- Large files that would consume too much memory if kept loaded\n\n- Sensitive data that shouldn't persist in memory\n\nWith 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.\n\nIn traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.\n\n### 3.6 Minimize Serialization at RSC Boundaries\n\n**Impact: HIGH (reduces data transfer size)**\n\nThe 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.\n\n**Incorrect: serializes all 50 fields**\n\n```tsx\nasync function Page() {\n const user = await fetchUser() // 50 fields\n return {user.name}
// uses 1 field\n}\n```\n\n**Correct: serializes only 1 field**\n\n```tsx\nasync function Page() {\n const user = await fetchUser()\n return {name}
\n}\n```\n\n### 3.7 Parallel Data Fetching with Component Composition\n\n**Impact: CRITICAL (eliminates server-side waterfalls)**\n\nReact Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.\n\n**Incorrect: Sidebar waits for Page's fetch to complete**\n\n```tsx\nexport default async function Page() {\n const header = await fetchHeader()\n return (\n \n
\n )\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n```\n\n**Correct: both fetch simultaneously**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {header}
\n {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nexport default function Page() {\n return (\n \n
\n )\n}\n```\n\n**Alternative with children prop:**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nfunction Layout({ children }: { children: ReactNode }) {\n return (\n \n
\n )\n}\n\nexport default function Page() {\n return (\n \n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct (wrapper shows immediately, data streams in):**\n\n```tsx\nfunction Page() {\n return (\n Sidebar
\n Header
\n \n
\n Footer
\n \n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return Sidebar
\n Header
\n \n
\n Footer
\n {data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative (share promise across components):**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n \n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return Sidebar
\n Header
\n Footer
\n {data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return {data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n- SEO-critical content above the fold\n- Small, fast queries where suspense overhead isn't worth it\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n","frontmatter":{"title":"Strategic Suspense Boundaries","impact":"HIGH","impactDescription":"faster initial paint","tags":"async, suspense, streaming, layout-shift"},"isInternal":false,"tokens":591,"sizeBytes":2510},{"name":"bundle-analyzable-paths.md","path":"skills/react-best-practices/rules/bundle-analyzable-paths.md","rawUrl":"https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-best-practices/rules/bundle-analyzable-paths.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Prefer Statically Analyzable Paths\nimpact: HIGH\nimpactDescription: avoids accidental broad bundles and file traces\ntags: bundle, nextjs, vite, webpack, rollup, esbuild, path\n---\n\n## Prefer Statically Analyzable Paths\n\nBuild 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.\n\nPrefer 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.\n\nWhen analysis becomes too broad, the cost is real:\n- Larger server bundles\n- Slower builds\n- Worse cold starts\n- More memory use\n\n### Import Paths\n\n**Incorrect (the bundler cannot tell what may be imported):**\n\n```ts\nconst PAGE_MODULES = {\n home: './pages/home',\n settings: './pages/settings',\n} as const\n\nconst Page = await import(PAGE_MODULES[pageName])\n```\n\n**Correct (use an explicit map of allowed modules):**\n\n```ts\nconst PAGE_MODULES = {\n home: () => import('./pages/home'),\n settings: () => import('./pages/settings'),\n} as const\n\nconst Page = await PAGE_MODULES[pageName]()\n```\n\n### File-System Paths\n\n**Incorrect (a 2-value enum still hides the final path from static analysis):**\n\n```ts\nconst baseDir = path.join(process.cwd(), 'content/' + contentKind)\n```\n\n**Correct (make each final path literal at the callsite):**\n\n```ts\nconst baseDir =\n kind === ContentKind.Blog\n ? path.join(process.cwd(), 'content/blog')\n : path.join(process.cwd(), 'content/docs')\n```\n\nIn 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.\n\nReference: [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/)\n","frontmatter":{"title":"Prefer Statically Analyzable Paths","impact":"HIGH","impactDescription":"avoids accidental broad bundles and file traces","tags":"bundle, nextjs, vite, webpack, rollup, esbuild, path"},"isInternal":false,"tokens":557,"sizeBytes":2382},{"name":"bundle-barrel-imports.md","path":"skills/react-best-practices/rules/bundle-barrel-imports.md","rawUrl":"https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-best-practices/rules/bundle-barrel-imports.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Avoid Barrel File Imports\nimpact: CRITICAL\nimpactDescription: 200-800ms import cost, slow builds\ntags: bundle, imports, tree-shaking, barrel-files, performance\n---\n\n## Avoid Barrel File Imports\n\nImport 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'`).\n\nPopular 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.\n\n**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.\n\n**Incorrect (imports entire library):**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct - Next.js 13.5+ (recommended):**\n\n```js\n// next.config.js - automatically optimizes barrel imports at build time\nmodule.exports = {\n experimental: {\n optimizePackageImports: ['lucide-react', '@mui/material']\n }\n}\n```\n\n```tsx\n// Keep the standard imports - Next.js transforms them to direct imports\nimport { Check, X, Menu } from 'lucide-react'\n// Full TypeScript support, no manual path wrangling\n```\n\nThis is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.\n\n**Correct - Direct imports (non-Next.js projects):**\n\n```tsx\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n> **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.\n\nThese optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries 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`.\n\nReference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n","frontmatter":{"title":"Avoid Barrel File Imports","impact":"CRITICAL","impactDescription":"200-800ms import cost, slow builds","tags":"bundle, imports, tree-shaking, barrel-files, performance"},"isInternal":false,"tokens":672,"sizeBytes":2795},{"name":"bundle-conditional.md","path":"skills/react-best-practices/rules/bundle-conditional.md","rawUrl":"https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-best-practices/rules/bundle-conditional.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Conditional Module Loading\nimpact: HIGH\nimpactDescription: loads large data only when needed\ntags: bundle, conditional-loading, lazy-loading\n---\n\n## Conditional Module Loading\n\nLoad large data or modules only when a feature is activated.\n\n**Example (lazy-load animation frames):**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.DispatchContent
\n}\n\n// Correct: toggle class\nfunction Box({ isHighlighted }: { isHighlighted: boolean }) {\n return (\n \n Content\n
\n )\n}\n```\n\nPrefer 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.\n\nSee [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.\n","frontmatter":{"title":"Avoid Layout Thrashing","impact":"MEDIUM","impactDescription":"prevents forced synchronous layouts and reduces performance bottlenecks","tags":"javascript, dom, css, performance, reflow, layout-thrashing"},"isInternal":false,"tokens":757,"sizeBytes":3266},{"name":"js-cache-function-results.md","path":"skills/react-best-practices/rules/js-cache-function-results.md","rawUrl":"https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-best-practices/rules/js-cache-function-results.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Cache Repeated Function Calls\nimpact: MEDIUM\nimpactDescription: avoid redundant computation\ntags: javascript, cache, memoization, performance\n---\n\n## Cache Repeated Function Calls\n\nUse a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.\n\n**Incorrect (redundant computation):**\n\n```typescript\nfunction ProjectList({ projects }: { projects: Project[] }) {\n return (\n \n {projects.map(project => {\n // slugify() called 100+ times for same project names\n const slug = slugify(project.name)\n \n return
\n )\n}\n```\n\n**Correct (cached results):**\n\n```typescript\n// Module-level cache\nconst slugifyCache = new Map\n {projects.map(project => {\n // Computed only once per unique project name\n const slug = cachedSlugify(project.name)\n \n return
\n )\n}\n```\n\n**Simpler pattern for single-value functions:**\n\n```typescript\nlet isLoggedInCache: boolean | null = null\n\nfunction isLoggedIn(): boolean {\n if (isLoggedInCache !== null) {\n return isLoggedInCache\n }\n \n isLoggedInCache = document.cookie.includes('auth=')\n return isLoggedInCache\n}\n\n// Clear cache when auth changes\nfunction onAuthChange() {\n isLoggedInCache = null\n}\n```\n\nUse a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.\n\nReference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)\n","frontmatter":{"title":"Cache Repeated Function Calls","impact":"MEDIUM","impactDescription":"avoid redundant computation","tags":"javascript, cache, memoization, performance"},"isInternal":false,"tokens":448,"sizeBytes":1949},{"name":"js-cache-property-access.md","path":"skills/react-best-practices/rules/js-cache-property-access.md","rawUrl":"https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-best-practices/rules/js-cache-property-access.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Cache Property Access in Loops\nimpact: LOW-MEDIUM\nimpactDescription: reduces lookups\ntags: javascript, loops, optimization, caching\n---\n\n## Cache Property Access in Loops\n\nCache object property lookups in hot paths.\n\n**Incorrect (3 lookups × N iterations):**\n\n```typescript\nfor (let i = 0; i < arr.length; i++) {\n process(obj.config.settings.value)\n}\n```\n\n**Correct (1 lookup total):**\n\n```typescript\nconst value = obj.config.settings.value\nconst len = arr.length\nfor (let i = 0; i < len; i++) {\n process(value)\n}\n```\n","frontmatter":{"title":"Cache Property Access in Loops","impact":"LOW-MEDIUM","impactDescription":"reduces lookups","tags":"javascript, loops, optimization, caching"},"isInternal":false,"tokens":138,"sizeBytes":532},{"name":"js-cache-storage.md","path":"skills/react-best-practices/rules/js-cache-storage.md","rawUrl":"https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-best-practices/rules/js-cache-storage.md","title":"Rules Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Cache Storage API Calls\nimpact: LOW-MEDIUM\nimpactDescription: reduces expensive I/O\ntags: javascript, localStorage, storage, caching, performance\n---\n\n## Cache Storage API Calls\n\n`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.\n\n**Incorrect (reads storage on every call):**\n\n```typescript\nfunction getTheme() {\n return localStorage.getItem('theme') ?? 'light'\n}\n// Called 10 times = 10 storage reads\n```\n\n**Correct (Map cache):**\n\n```typescript\nconst storageCache = new Map\n
\n )\n}\n```\n\nThe entire layout waits for data even though only the middle section needs it.\n\n**Correct: wrapper shows immediately, data streams in**\n\n```tsx\nfunction Page() {\n return (\n Sidebar
\n Header
\n \n
\n Footer
\n \n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return Sidebar
\n Header
\n \n
\n Footer
\n {data.content}
\n}\n```\n\nSidebar, Header, and Footer render immediately. Only DataDisplay waits for data.\n\n**Alternative: share promise across components**\n\n```tsx\nfunction Page() {\n // Start fetch immediately, but don't await\n const dataPromise = fetchData()\n \n return (\n \n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return Sidebar
\n Header
\n Footer
\n {data.content}
\n}\n\nfunction DataSummary({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Reuses the same promise\n return {data.summary}
\n}\n```\n\nBoth components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.\n\n**When NOT to use this pattern:**\n\n- Critical data needed for layout decisions (affects positioning)\n\n- SEO-critical content above the fold\n\n- Small, fast queries where suspense overhead isn't worth it\n\n- When you want to avoid layout shift (loading → content jump)\n\n**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.\n\n---\n\n## 2. Bundle Size Optimization\n\n**Impact: CRITICAL**\n\nReducing initial bundle size improves Time to Interactive and Largest Contentful Paint.\n\n### 2.1 Avoid Barrel File Imports\n\n**Impact: CRITICAL (200-800ms import cost, slow builds)**\n\nImport 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'`).\n\nPopular 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.\n\n**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.\n\n**Incorrect: imports entire library**\n\n```tsx\nimport { Check, X, Menu } from 'lucide-react'\n// Loads 1,583 modules, takes ~2.8s extra in dev\n// Runtime cost: 200-800ms on every cold start\n\nimport { Button, TextField } from '@mui/material'\n// Loads 2,225 modules, takes ~4.2s extra in dev\n```\n\n**Correct - Next.js 13.5+ (recommended):**\n\n```tsx\n// Keep the standard imports - Next.js transforms them to direct imports\nimport { Check, X, Menu } from 'lucide-react'\n// Full TypeScript support, no manual path wrangling\n```\n\nThis is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.\n\n**Correct - Direct imports (non-Next.js projects):**\n\n```tsx\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use\n```\n\n> **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.\n\nThese optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.\n\nLibraries 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`.\n\nReference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)\n\n### 2.2 Conditional Module Loading\n\n**Impact: HIGH (loads large data only when needed)**\n\nLoad large data or modules only when a feature is activated.\n\n**Example: lazy-load animation frames**\n\n```tsx\nfunction AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch{currentUser?.name}
\n}\n```\n\nIf two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.\n\n**Correct: keep request data local to the render tree**\n\n```tsx\nexport default async function Page() {\n const user = await auth()\n return {user?.name}
\n}\n```\n\nSafe exceptions:\n\n- Immutable static assets or config loaded once at module scope\n\n- Shared caches intentionally designed for cross-request reuse and keyed correctly\n\n- Process-wide singletons that do not store request- or user-specific mutable data\n\nFor static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).\n\n### 3.4 Cross-Request LRU Caching\n\n**Impact: HIGH (caches across requests)**\n\n`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.\n\n**Implementation:**\n\n```typescript\nimport { LRUCache } from 'lru-cache'\n\nconst cache = new LRUCache\n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Correct: loads once at module initialization**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\n\n// Module-level: runs ONCE when module is first imported\nconst fontData = fetch(\n new URL('./fonts/Inter.ttf', import.meta.url)\n).then(res => res.arrayBuffer())\n\nconst logoData = fetch(\n new URL('./images/logo.png', import.meta.url)\n).then(res => res.arrayBuffer())\n\nexport async function GET(request: Request) {\n // Await the already-started promises\n const [font, logo] = await Promise.all([fontData, logoData])\n\n return new ImageResponse(\n \n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: font }] }\n )\n}\n```\n\n**Correct: synchronous fs at module level**\n\n```typescript\n// app/api/og/route.tsx\nimport { ImageResponse } from 'next/og'\nimport { readFileSync } from 'fs'\nimport { join } from 'path'\n\n// Synchronous read at module level - blocks only during module init\nconst fontData = readFileSync(\n join(process.cwd(), 'public/fonts/Inter.ttf')\n)\n\nconst logoData = readFileSync(\n join(process.cwd(), 'public/images/logo.png')\n)\n\nexport async function GET(request: Request) {\n return new ImageResponse(\n \n \n Hello World\n
,\n { fonts: [{ name: 'Inter', data: fontData }] }\n )\n}\n```\n\n**Incorrect: reads config on every call**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nexport async function processRequest(data: Data) {\n const config = JSON.parse(\n await fs.readFile('./config.json', 'utf-8')\n )\n const template = await fs.readFile('./template.html', 'utf-8')\n\n return render(template, data, config)\n}\n```\n\n**Correct: hoists config and template to module level**\n\n```typescript\nimport fs from 'node:fs/promises'\n\nconst configPromise = fs\n .readFile('./config.json', 'utf-8')\n .then(JSON.parse)\nconst templatePromise = fs.readFile('./template.html', 'utf-8')\n\nexport async function processRequest(data: Data) {\n const [config, template] = await Promise.all([\n configPromise,\n templatePromise,\n ])\n\n return render(template, data, config)\n}\n```\n\nWhen to use this pattern:\n\n- Loading fonts for OG image generation\n\n- Loading static logos, icons, or watermarks\n\n- Reading configuration files that don't change at runtime\n\n- Loading email templates or other static templates\n\n- Any static asset that's the same across all requests\n\nWhen not to use this pattern:\n\n- Assets that vary per request or user\n\n- Files that may change during runtime (use caching with TTL instead)\n\n- Large files that would consume too much memory if kept loaded\n\n- Sensitive data that shouldn't persist in memory\n\nWith 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.\n\nIn traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.\n\n### 3.6 Minimize Serialization at RSC Boundaries\n\n**Impact: HIGH (reduces data transfer size)**\n\nThe 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.\n\n**Incorrect: serializes all 50 fields**\n\n```tsx\nasync function Page() {\n const user = await fetchUser() // 50 fields\n return {user.name}
// uses 1 field\n}\n```\n\n**Correct: serializes only 1 field**\n\n```tsx\nasync function Page() {\n const user = await fetchUser()\n return {name}
\n}\n```\n\n### 3.7 Parallel Data Fetching with Component Composition\n\n**Impact: CRITICAL (eliminates server-side waterfalls)**\n\nReact Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.\n\n**Incorrect: Sidebar waits for Page's fetch to complete**\n\n```tsx\nexport default async function Page() {\n const header = await fetchHeader()\n return (\n \n
\n )\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n```\n\n**Correct: both fetch simultaneously**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {header}
\n {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nexport default function Page() {\n return (\n \n
\n )\n}\n```\n\n**Alternative with children prop:**\n\n```tsx\nasync function Header() {\n const data = await fetchHeader()\n return {data}
\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return \n}\n\nfunction Layout({ children }: { children: ReactNode }) {\n return (\n \n
\n )\n}\n\nexport default function Page() {\n return (\n