{"owner":"zhukunpenglinyutong","repo":"jetbrains-cc-gui","hasSkills":true,"totalSkillsCount":81,"totalTokensCount":40510,"categories":["anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/vercel-react-best-practices/README.md",".agents/skills/vercel-react-best-practices/SKILL.md",".agents/skills/vercel-react-best-practices/metadata.json",".agents/skills/vercel-react-best-practices/rules/_sections.md",".agents/skills/vercel-react-best-practices/rules/_template.md",".agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md",".agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md",".agents/skills/vercel-react-best-practices/rules/advanced-init-once.md",".agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md",".agents/skills/vercel-react-best-practices/rules/async-api-routes.md",".agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md",".agents/skills/vercel-react-best-practices/rules/async-defer-await.md",".agents/skills/vercel-react-best-practices/rules/async-dependencies.md",".agents/skills/vercel-react-best-practices/rules/async-parallel.md",".agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md",".agents/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md",".agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md",".agents/skills/vercel-react-best-practices/rules/bundle-conditional.md",".agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md",".agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md",".agents/skills/vercel-react-best-practices/rules/bundle-preload.md",".agents/skills/vercel-react-best-practices/rules/client-event-listeners.md",".agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md",".agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md",".agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md",".agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md",".agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md",".agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md",".agents/skills/vercel-react-best-practices/rules/js-cache-storage.md",".agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md",".agents/skills/vercel-react-best-practices/rules/js-early-exit.md",".agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md",".agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md",".agents/skills/vercel-react-best-practices/rules/js-index-maps.md",".agents/skills/vercel-react-best-practices/rules/js-length-check-first.md",".agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md",".agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md",".agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md",".agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md",".agents/skills/vercel-react-best-practices/rules/rendering-activity.md",".agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md",".agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md",".agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md",".agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md",".agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md",".agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md",".agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md",".agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md",".agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md",".agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md",".agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md",".agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md",".agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md",".agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md",".agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md",".agents/skills/vercel-react-best-practices/rules/rerender-memo.md",".agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md",".agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md",".agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md",".agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md",".agents/skills/vercel-react-best-practices/rules/rerender-transitions.md",".agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md",".agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md",".agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md",".agents/skills/vercel-react-best-practices/rules/server-auth-actions.md",".agents/skills/vercel-react-best-practices/rules/server-cache-lru.md",".agents/skills/vercel-react-best-practices/rules/server-cache-react.md",".agents/skills/vercel-react-best-practices/rules/server-dedup-props.md",".agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md",".agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md",".agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md",".agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md",".agents/skills/vercel-react-best-practices/rules/server-serialization.md","docs/skills/SLASH_COMMANDS.md","docs/skills/avoiding-tmp-writes.md","docs/skills/cmdline-argument-escaping-bug.md","docs/skills/multimodal-permission-bug.md","docs/skills/tempdir-permission-sync.md","docs/skills/windows-cli-path-bug.md"],"skills":{".agents/skills/vercel-react-best-practices/README.md":"# React Best Practices\n\nA structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.\n\n## Structure\n\n- `rules/` - Individual rule files (one per rule)\n - `_sections.md` - Section metadata (titles, impacts, descriptions)\n - `_template.md` - Template for creating new rules\n - `area-description.md` - Individual rule files\n- `src/` - Build scripts and utilities\n- `metadata.json` - Document metadata (version, organization, abstract)\n- __`AGENTS.md`__ - Compiled output (generated)\n- __`test-cases.json`__ - Test cases for LLM evaluation (generated)\n\n## Getting Started\n\n1. Install dependencies:\n ```bash\n pnpm install\n ```\n\n2. Build AGENTS.md from rules:\n ```bash\n pnpm build\n ```\n\n3. Validate rule files:\n ```bash\n pnpm validate\n ```\n\n4. Extract test cases:\n ```bash\n pnpm extract-tests\n ```\n\n## Creating a New Rule\n\n1. Copy `rules/_template.md` to `rules/area-description.md`\n2. Choose the appropriate area prefix:\n - `async-` for Eliminating Waterfalls (Section 1)\n - `bundle-` for Bundle Size Optimization (Section 2)\n - `server-` for Server-Side Performance (Section 3)\n - `client-` for Client-Side Data Fetching (Section 4)\n - `rerender-` for Re-render Optimization (Section 5)\n - `rendering-` for Rendering Performance (Section 6)\n - `js-` for JavaScript Performance (Section 7)\n - `advanced-` for Advanced Patterns (Section 8)\n3. Fill in the frontmatter and content\n4. Ensure you have clear examples with explanations\n5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json\n\n## Rule File Structure\n\nEach rule file should follow this structure:\n\n```markdown\n---\ntitle: Rule Title Here\nimpact: MEDIUM\nimpactDescription: Optional description\ntags: tag1, tag2, tag3\n---\n\n## Rule Title Here\n\nBrief explanation of the rule and why it matters.\n\n**Incorrect (description of what's wrong):**\n\n```typescript\n// Bad code example\n```\n\n**Correct (description of what's right):**\n\n```typescript\n// Good code example\n```\n\nOptional explanatory text after examples.\n\nReference: [Link](https://example.com)\n\n## File Naming Convention\n\n- Files starting with `_` are special (excluded from build)\n- Rule files: `area-description.md` (e.g., `async-parallel.md`)\n- Section is automatically inferred from filename prefix\n- Rules are sorted alphabetically by title within each section\n- IDs (e.g., 1.1, 1.2) are auto-generated during build\n\n## Impact Levels\n\n- `CRITICAL` - Highest priority, major performance gains\n- `HIGH` - Significant performance improvements\n- `MEDIUM-HIGH` - Moderate-high gains\n- `MEDIUM` - Moderate performance improvements\n- `LOW-MEDIUM` - Low-medium gains\n- `LOW` - Incremental improvements\n\n## Scripts\n\n- `pnpm build` - Compile rules into AGENTS.md\n- `pnpm validate` - Validate all rule files\n- `pnpm extract-tests` - Extract test cases for LLM evaluation\n- `pnpm dev` - Build and validate\n\n## Contributing\n\nWhen adding or modifying rules:\n\n1. Use the correct filename prefix for your section\n2. Follow the `_template.md` structure\n3. Include clear bad/good examples with explanations\n4. Add appropriate tags\n5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json\n6. Rules are automatically sorted by title - no need to manage numbers!\n\n## Acknowledgments\n\nOriginally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).\n",".agents/skills/vercel-react-best-practices/SKILL.md":"",".agents/skills/vercel-react-best-practices/metadata.json":"{\n \"version\": \"1.0.0\",\n \"organization\": \"Vercel Engineering\",\n \"date\": \"January 2026\",\n \"abstract\": \"Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.\",\n \"references\": [\n \"https://react.dev\",\n \"https://nextjs.org\",\n \"https://swr.vercel.app\",\n \"https://github.com/shuding/better-all\",\n \"https://github.com/isaacs/node-lru-cache\",\n \"https://vercel.com/blog/how-we-optimized-package-imports-in-next-js\",\n \"https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast\"\n ]\n}\n",".agents/skills/vercel-react-best-practices/rules/_sections.md":"# Sections\n\nThis file defines all sections, their ordering, impact levels, and descriptions.\nThe section ID (in parentheses) is the filename prefix used to group rules.\n\n---\n\n## 1. Eliminating Waterfalls (async)\n\n**Impact:** CRITICAL \n**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.\n\n## 2. Bundle Size Optimization (bundle)\n\n**Impact:** CRITICAL \n**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.\n\n## 3. Server-Side Performance (server)\n\n**Impact:** HIGH \n**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.\n\n## 4. Client-Side Data Fetching (client)\n\n**Impact:** MEDIUM-HIGH \n**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.\n\n## 5. Re-render Optimization (rerender)\n\n**Impact:** MEDIUM \n**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.\n\n## 6. Rendering Performance (rendering)\n\n**Impact:** MEDIUM \n**Description:** Optimizing the rendering process reduces the work the browser needs to do.\n\n## 7. JavaScript Performance (js)\n\n**Impact:** LOW-MEDIUM \n**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.\n\n## 8. Advanced Patterns (advanced)\n\n**Impact:** LOW \n**Description:** Advanced patterns for specific cases that require careful implementation.\n",".agents/skills/vercel-react-best-practices/rules/_template.md":"---\ntitle: Rule Title Here\nimpact: MEDIUM\nimpactDescription: Optional description of impact (e.g., \"20-50% improvement\")\ntags: tag1, tag2\n---\n\n## Rule Title Here\n\n**Impact: MEDIUM (optional impact description)**\n\nBrief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.\n\n**Incorrect (description of what's wrong):**\n\n```typescript\n// Bad code example here\nconst bad = example()\n```\n\n**Correct (description of what's right):**\n\n```typescript\n// Good code example here\nconst good = example()\n```\n\nReference: [Link to documentation or resource](https://example.com)\n",".agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md":"---\ntitle: Do Not Put Effect Events in Dependency Arrays\nimpact: LOW\nimpactDescription: avoids unnecessary effect re-runs and lint errors\ntags: advanced, hooks, useEffectEvent, dependencies, effects\n---\n\n## Do Not Put Effect Events in Dependency Arrays\n\nEffect 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.\n\n**Incorrect (Effect Event added as a dependency):**\n\n```tsx\nimport { useEffect, useEffectEvent } from 'react'\n\nfunction ChatRoom({ roomId, onConnected }: {\n roomId: string\n onConnected: () => void\n}) {\n const handleConnected = useEffectEvent(onConnected)\n\n useEffect(() => {\n const connection = createConnection(roomId)\n connection.on('connected', handleConnected)\n connection.connect()\n\n return () => connection.disconnect()\n }, [roomId, handleConnected])\n}\n```\n\nIncluding the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.\n\n**Correct (depend on reactive values, not the Effect Event):**\n\n```tsx\nimport { useEffect, useEffectEvent } from 'react'\n\nfunction ChatRoom({ roomId, onConnected }: {\n roomId: string\n onConnected: () => void\n}) {\n const handleConnected = useEffectEvent(onConnected)\n\n useEffect(() => {\n const connection = createConnection(roomId)\n connection.on('connected', handleConnected)\n connection.connect()\n\n return () => connection.disconnect()\n }, [roomId])\n}\n```\n\nReference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)\n",".agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md":"---\ntitle: Store Event Handlers in Refs\nimpact: LOW\nimpactDescription: stable subscriptions\ntags: advanced, hooks, refs, event-handlers, optimization\n---\n\n## Store Event Handlers in Refs\n\nStore callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.\n\n**Incorrect (re-subscribes on every render):**\n\n```tsx\nfunction useWindowEvent(event: string, handler: (e) => void) {\n useEffect(() => {\n window.addEventListener(event, handler)\n return () => window.removeEventListener(event, handler)\n }, [event, handler])\n}\n```\n\n**Correct (stable subscription):**\n\n```tsx\nfunction useWindowEvent(event: string, handler: (e) => void) {\n const handlerRef = useRef(handler)\n useEffect(() => {\n handlerRef.current = handler\n }, [handler])\n\n useEffect(() => {\n const listener = (e) => handlerRef.current(e)\n window.addEventListener(event, listener)\n return () => window.removeEventListener(event, listener)\n }, [event])\n}\n```\n\n**Alternative: use `useEffectEvent` if you're on latest React:**\n\n```tsx\nimport { useEffectEvent } from 'react'\n\nfunction useWindowEvent(event: string, handler: (e) => void) {\n const onEvent = useEffectEvent(handler)\n\n useEffect(() => {\n window.addEventListener(event, onEvent)\n return () => window.removeEventListener(event, onEvent)\n }, [event])\n}\n```\n\n`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.\n",".agents/skills/vercel-react-best-practices/rules/advanced-init-once.md":"---\ntitle: Initialize App Once, Not Per Mount\nimpact: LOW-MEDIUM\nimpactDescription: avoids duplicate init in development\ntags: initialization, useEffect, app-startup, side-effects\n---\n\n## Initialize App Once, Not Per Mount\n\nDo 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.\n\n**Incorrect (runs twice in dev, re-runs on remount):**\n\n```tsx\nfunction Comp() {\n useEffect(() => {\n loadFromStorage()\n checkAuthToken()\n }, [])\n\n // ...\n}\n```\n\n**Correct (once per app load):**\n\n```tsx\nlet didInit = false\n\nfunction Comp() {\n useEffect(() => {\n if (didInit) return\n didInit = true\n loadFromStorage()\n checkAuthToken()\n }, [])\n\n // ...\n}\n```\n\nReference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)\n",".agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md":"---\ntitle: useEffectEvent for Stable Callback Refs\nimpact: LOW\nimpactDescription: prevents effect re-runs\ntags: advanced, hooks, useEffectEvent, refs, optimization\n---\n\n## useEffectEvent for Stable Callback Refs\n\nAccess latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.\n\n**Incorrect (effect re-runs on every callback change):**\n\n```tsx\nfunction SearchInput({ onSearch }: { onSearch: (q: string) => void }) {\n const [query, setQuery] = useState('')\n\n useEffect(() => {\n const timeout = setTimeout(() => onSearch(query), 300)\n return () => clearTimeout(timeout)\n }, [query, onSearch])\n}\n```\n\n**Correct (using React's useEffectEvent):**\n\n```tsx\nimport { useEffectEvent } from 'react';\n\nfunction SearchInput({ onSearch }: { onSearch: (q: string) => void }) {\n const [query, setQuery] = useState('')\n const onSearchEvent = useEffectEvent(onSearch)\n\n useEffect(() => {\n const timeout = setTimeout(() => onSearchEvent(query), 300)\n return () => clearTimeout(timeout)\n }, [query])\n}\n```\n",".agents/skills/vercel-react-best-practices/rules/async-api-routes.md":"---\ntitle: Prevent Waterfall Chains in API Routes\nimpact: CRITICAL\nimpactDescription: 2-10× improvement\ntags: api-routes, server-actions, waterfalls, parallelization\n---\n\n## Prevent Waterfall Chains in API Routes\n\nIn API routes and Server Actions, start independent operations immediately, even if you don't await them yet.\n\n**Incorrect (config waits for auth, data waits for both):**\n\n```typescript\nexport async function GET(request: Request) {\n const session = await auth()\n const config = await fetchConfig()\n const data = await fetchData(session.user.id)\n return Response.json({ data, config })\n}\n```\n\n**Correct (auth and config start immediately):**\n\n```typescript\nexport async function GET(request: Request) {\n const sessionPromise = auth()\n const configPromise = fetchConfig()\n const session = await sessionPromise\n const [config, data] = await Promise.all([\n configPromise,\n fetchData(session.user.id)\n ])\n return Response.json({ data, config })\n}\n```\n\nFor operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).\n",".agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md":"---\ntitle: Check Cheap Conditions Before Async Flags\nimpact: HIGH\nimpactDescription: avoids unnecessary async work when a synchronous guard already fails\ntags: async, await, feature-flags, short-circuit, conditional\n---\n\n## Check Cheap Conditions Before Async Flags\n\nWhen 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.\n\nThis is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.\n\n**Incorrect:**\n\n```typescript\nconst someFlag = await getFlag()\n\nif (someFlag && someCondition) {\n // ...\n}\n```\n\n**Correct:**\n\n```typescript\nif (someCondition) {\n const someFlag = await getFlag()\n if (someFlag) {\n // ...\n }\n}\n```\n\nThis 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.\n\nKeep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.\n",".agents/skills/vercel-react-best-practices/rules/async-defer-await.md":"---\ntitle: Defer Await Until Needed\nimpact: HIGH\nimpactDescription: avoids blocking unused code paths\ntags: async, await, conditional, optimization\n---\n\n## Defer Await Until Needed\n\nMove `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.\n\n**Incorrect (blocks both branches):**\n\n```typescript\nasync function handleRequest(userId: string, skipProcessing: boolean) {\n const userData = await fetchUserData(userId)\n \n if (skipProcessing) {\n // Returns immediately but still waited for userData\n return { skipped: true }\n }\n \n // Only this branch uses userData\n return processUserData(userData)\n}\n```\n\n**Correct (only blocks when needed):**\n\n```typescript\nasync function handleRequest(userId: string, skipProcessing: boolean) {\n if (skipProcessing) {\n // Returns immediately without waiting\n return { skipped: true }\n }\n \n // Fetch only when needed\n const userData = await fetchUserData(userId)\n return processUserData(userData)\n}\n```\n\n**Another example (early return optimization):**\n\n```typescript\n// Incorrect: always fetches permissions\nasync function updateResource(resourceId: string, userId: string) {\n const permissions = await fetchPermissions(userId)\n const resource = await getResource(resourceId)\n \n if (!resource) {\n return { error: 'Not found' }\n }\n \n if (!permissions.canEdit) {\n return { error: 'Forbidden' }\n }\n \n return await updateResourceData(resource, permissions)\n}\n\n// Correct: fetches only when needed\nasync function updateResource(resourceId: string, userId: string) {\n const resource = await getResource(resourceId)\n \n if (!resource) {\n return { error: 'Not found' }\n }\n \n const permissions = await fetchPermissions(userId)\n \n if (!permissions.canEdit) {\n return { error: 'Forbidden' }\n }\n \n return await updateResourceData(resource, permissions)\n}\n```\n\nThis optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.\n\nFor `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).\n",".agents/skills/vercel-react-best-practices/rules/async-dependencies.md":"---\ntitle: Dependency-Based Parallelization\nimpact: CRITICAL\nimpactDescription: 2-10× improvement\ntags: async, parallelization, dependencies, better-all\n---\n\n## Dependency-Based Parallelization\n\nFor operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.\n\n**Incorrect (profile waits for config unnecessarily):**\n\n```typescript\nconst [user, config] = await Promise.all([\n fetchUser(),\n fetchConfig()\n])\nconst profile = await fetchProfile(user.id)\n```\n\n**Correct (config and profile run in parallel):**\n\n```typescript\nimport { all } from 'better-all'\n\nconst { user, config, profile } = await all({\n async user() { return fetchUser() },\n async config() { return fetchConfig() },\n async profile() {\n return fetchProfile((await this.$.user).id)\n }\n})\n```\n\n**Alternative without extra dependencies:**\n\nWe can also create all the promises first, and do `Promise.all()` at the end.\n\n```typescript\nconst userPromise = fetchUser()\nconst profilePromise = userPromise.then(user => fetchProfile(user.id))\n\nconst [user, config, profile] = await Promise.all([\n userPromise,\n fetchConfig(),\n profilePromise\n])\n```\n\nReference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)\n",".agents/skills/vercel-react-best-practices/rules/async-parallel.md":"---\ntitle: Promise.all() for Independent Operations\nimpact: CRITICAL\nimpactDescription: 2-10× improvement\ntags: async, parallelization, promises, waterfalls\n---\n\n## Promise.all() for Independent Operations\n\nWhen async operations have no interdependencies, execute them concurrently using `Promise.all()`.\n\n**Incorrect (sequential execution, 3 round trips):**\n\n```typescript\nconst user = await fetchUser()\nconst posts = await fetchPosts()\nconst comments = await fetchComments()\n```\n\n**Correct (parallel execution, 1 round trip):**\n\n```typescript\nconst [user, posts, comments] = await Promise.all([\n fetchUser(),\n fetchPosts(),\n fetchComments()\n])\n```\n",".agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md":"---\ntitle: Strategic Suspense Boundaries\nimpact: HIGH\nimpactDescription: faster initial paint\ntags: async, suspense, streaming, layout-shift\n---\n\n## Strategic Suspense Boundaries\n\nInstead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.\n\n**Incorrect (wrapper blocked by data fetching):**\n\n```tsx\nasync function Page() {\n const data = await fetchData() // Blocks entire page\n \n return (\n
\n
Sidebar
\n
Header
\n
\n \n
\n
Footer
\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
\n
Sidebar
\n
Header
\n
\n }>\n \n \n
\n
Footer
\n
\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return
{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
Sidebar
\n
Header
\n }>\n \n \n \n
Footer
\n
\n )\n}\n\nfunction DataDisplay({ dataPromise }: { dataPromise: Promise }) {\n const data = use(dataPromise) // Unwraps the promise\n return
{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",".agents/skills/vercel-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",".agents/skills/vercel-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",".agents/skills/vercel-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.Dispatch> }) {\n const [frames, setFrames] = useState(null)\n\n useEffect(() => {\n if (enabled && !frames && typeof window !== 'undefined') {\n import('./animation-frames.js')\n .then(mod => setFrames(mod.frames))\n .catch(() => setEnabled(false))\n }\n }, [enabled, frames, setEnabled])\n\n if (!frames) return \n return \n}\n```\n\nThe `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.\n",".agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md":"---\ntitle: Defer Non-Critical Third-Party Libraries\nimpact: MEDIUM\nimpactDescription: loads after hydration\ntags: bundle, third-party, analytics, defer\n---\n\n## Defer Non-Critical Third-Party Libraries\n\nAnalytics, logging, and error tracking don't block user interaction. Load them after hydration.\n\n**Incorrect (blocks initial bundle):**\n\n```tsx\nimport { Analytics } from '@vercel/analytics/react'\n\nexport default function RootLayout({ children }) {\n return (\n \n \n {children}\n \n \n \n )\n}\n```\n\n**Correct (loads after hydration):**\n\n```tsx\nimport dynamic from 'next/dynamic'\n\nconst Analytics = dynamic(\n () => import('@vercel/analytics/react').then(m => m.Analytics),\n { ssr: false }\n)\n\nexport default function RootLayout({ children }) {\n return (\n \n \n {children}\n \n \n \n )\n}\n```\n",".agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md":"---\ntitle: Dynamic Imports for Heavy Components\nimpact: CRITICAL\nimpactDescription: directly affects TTI and LCP\ntags: bundle, dynamic-import, code-splitting, next-dynamic\n---\n\n## Dynamic Imports for Heavy Components\n\nUse `next/dynamic` to lazy-load large components not needed on initial render.\n\n**Incorrect (Monaco bundles with main chunk ~300KB):**\n\n```tsx\nimport { MonacoEditor } from './monaco-editor'\n\nfunction CodePanel({ code }: { code: string }) {\n return \n}\n```\n\n**Correct (Monaco loads on demand):**\n\n```tsx\nimport dynamic from 'next/dynamic'\n\nconst MonacoEditor = dynamic(\n () => import('./monaco-editor').then(m => m.MonacoEditor),\n { ssr: false }\n)\n\nfunction CodePanel({ code }: { code: string }) {\n return \n}\n```\n",".agents/skills/vercel-react-best-practices/rules/bundle-preload.md":"---\ntitle: Preload Based on User Intent\nimpact: MEDIUM\nimpactDescription: reduces perceived latency\ntags: bundle, preload, user-intent, hover\n---\n\n## Preload Based on User Intent\n\nPreload heavy bundles before they're needed to reduce perceived latency.\n\n**Example (preload on hover/focus):**\n\n```tsx\nfunction EditorButton({ onClick }: { onClick: () => void }) {\n const preload = () => {\n if (typeof window !== 'undefined') {\n void import('./monaco-editor')\n }\n }\n\n return (\n \n Open Editor\n \n )\n}\n```\n\n**Example (preload when feature flag is enabled):**\n\n```tsx\nfunction FlagsProvider({ children, flags }: Props) {\n useEffect(() => {\n if (flags.editorEnabled && typeof window !== 'undefined') {\n void import('./monaco-editor').then(mod => mod.init())\n }\n }, [flags.editorEnabled])\n\n return \n {children}\n \n}\n```\n\nThe `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.\n",".agents/skills/vercel-react-best-practices/rules/client-event-listeners.md":"---\ntitle: Deduplicate Global Event Listeners\nimpact: LOW\nimpactDescription: single listener for N components\ntags: client, swr, event-listeners, subscription\n---\n\n## Deduplicate Global Event Listeners\n\nUse `useSWRSubscription()` to share global event listeners across component instances.\n\n**Incorrect (N instances = N listeners):**\n\n```tsx\nfunction useKeyboardShortcut(key: string, callback: () => void) {\n useEffect(() => {\n const handler = (e: KeyboardEvent) => {\n if (e.metaKey && e.key === key) {\n callback()\n }\n }\n window.addEventListener('keydown', handler)\n return () => window.removeEventListener('keydown', handler)\n }, [key, callback])\n}\n```\n\nWhen using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.\n\n**Correct (N instances = 1 listener):**\n\n```tsx\nimport useSWRSubscription from 'swr/subscription'\n\n// Module-level Map to track callbacks per key\nconst keyCallbacks = new Map void>>()\n\nfunction useKeyboardShortcut(key: string, callback: () => void) {\n // Register this callback in the Map\n useEffect(() => {\n if (!keyCallbacks.has(key)) {\n keyCallbacks.set(key, new Set())\n }\n keyCallbacks.get(key)!.add(callback)\n\n return () => {\n const set = keyCallbacks.get(key)\n if (set) {\n set.delete(callback)\n if (set.size === 0) {\n keyCallbacks.delete(key)\n }\n }\n }\n }, [key, callback])\n\n useSWRSubscription('global-keydown', () => {\n const handler = (e: KeyboardEvent) => {\n if (e.metaKey && keyCallbacks.has(e.key)) {\n keyCallbacks.get(e.key)!.forEach(cb => cb())\n }\n }\n window.addEventListener('keydown', handler)\n return () => window.removeEventListener('keydown', handler)\n })\n}\n\nfunction Profile() {\n // Multiple shortcuts will share the same listener\n useKeyboardShortcut('p', () => { /* ... */ }) \n useKeyboardShortcut('k', () => { /* ... */ })\n // ...\n}\n```\n",".agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md":"---\ntitle: Version and Minimize localStorage Data\nimpact: MEDIUM\nimpactDescription: prevents schema conflicts, reduces storage size\ntags: client, localStorage, storage, versioning, data-minimization\n---\n\n## Version and Minimize localStorage Data\n\nAdd version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.\n\n**Incorrect:**\n\n```typescript\n// No version, stores everything, no error handling\nlocalStorage.setItem('userConfig', JSON.stringify(fullUserObject))\nconst data = localStorage.getItem('userConfig')\n```\n\n**Correct:**\n\n```typescript\nconst VERSION = 'v2'\n\nfunction saveConfig(config: { theme: string; language: string }) {\n try {\n localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))\n } catch {\n // Throws in incognito/private browsing, quota exceeded, or disabled\n }\n}\n\nfunction loadConfig() {\n try {\n const data = localStorage.getItem(`userConfig:${VERSION}`)\n return data ? JSON.parse(data) : null\n } catch {\n return null\n }\n}\n\n// Migration from v1 to v2\nfunction migrate() {\n try {\n const v1 = localStorage.getItem('userConfig:v1')\n if (v1) {\n const old = JSON.parse(v1)\n saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })\n localStorage.removeItem('userConfig:v1')\n }\n } catch {}\n}\n```\n\n**Store minimal fields from server responses:**\n\n```typescript\n// User object has 20+ fields, only store what UI needs\nfunction cachePrefs(user: FullUser) {\n try {\n localStorage.setItem('prefs:v1', JSON.stringify({\n theme: user.preferences.theme,\n notifications: user.preferences.notifications\n }))\n } catch {}\n}\n```\n\n**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.\n\n**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.\n",".agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md":"---\ntitle: Use Passive Event Listeners for Scrolling Performance\nimpact: MEDIUM\nimpactDescription: eliminates scroll delay caused by event listeners\ntags: client, event-listeners, scrolling, performance, touch, wheel\n---\n\n## Use Passive Event Listeners for Scrolling Performance\n\nAdd `{ 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.\n\n**Incorrect:**\n\n```typescript\nuseEffect(() => {\n const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)\n const handleWheel = (e: WheelEvent) => console.log(e.deltaY)\n \n document.addEventListener('touchstart', handleTouch)\n document.addEventListener('wheel', handleWheel)\n \n return () => {\n document.removeEventListener('touchstart', handleTouch)\n document.removeEventListener('wheel', handleWheel)\n }\n}, [])\n```\n\n**Correct:**\n\n```typescript\nuseEffect(() => {\n const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)\n const handleWheel = (e: WheelEvent) => console.log(e.deltaY)\n \n document.addEventListener('touchstart', handleTouch, { passive: true })\n document.addEventListener('wheel', handleWheel, { passive: true })\n \n return () => {\n document.removeEventListener('touchstart', handleTouch)\n document.removeEventListener('wheel', handleWheel)\n }\n}, [])\n```\n\n**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.\n\n**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.\n",".agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md":"---\ntitle: Use SWR for Automatic Deduplication\nimpact: MEDIUM-HIGH\nimpactDescription: automatic deduplication\ntags: client, swr, deduplication, data-fetching\n---\n\n## Use SWR for Automatic Deduplication\n\nSWR enables request deduplication, caching, and revalidation across component instances.\n\n**Incorrect (no deduplication, each instance fetches):**\n\n```tsx\nfunction UserList() {\n const [users, setUsers] = useState([])\n useEffect(() => {\n fetch('/api/users')\n .then(r => r.json())\n .then(setUsers)\n }, [])\n}\n```\n\n**Correct (multiple instances share one request):**\n\n```tsx\nimport useSWR from 'swr'\n\nfunction UserList() {\n const { data: users } = useSWR('/api/users', fetcher)\n}\n```\n\n**For immutable data:**\n\n```tsx\nimport { useImmutableSWR } from '@/lib/swr'\n\nfunction StaticContent() {\n const { data } = useImmutableSWR('/api/config', fetcher)\n}\n```\n\n**For mutations:**\n\n```tsx\nimport { useSWRMutation } from 'swr/mutation'\n\nfunction UpdateButton() {\n const { trigger } = useSWRMutation('/api/user', updateUser)\n return \n}\n```\n\nReference: [https://swr.vercel.app](https://swr.vercel.app)\n",".agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md":"---\ntitle: Avoid Layout Thrashing\nimpact: MEDIUM\nimpactDescription: prevents forced synchronous layouts and reduces performance bottlenecks\ntags: javascript, dom, css, performance, reflow, layout-thrashing\n---\n\n## Avoid Layout Thrashing\n\nAvoid 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.\n\n**This is OK (browser batches style changes):**\n```typescript\nfunction updateElementStyles(element: HTMLElement) {\n // Each line invalidates style, but browser batches the recalculation\n element.style.width = '100px'\n element.style.height = '200px'\n element.style.backgroundColor = 'blue'\n element.style.border = '1px solid black'\n}\n```\n\n**Incorrect (interleaved reads and writes force reflows):**\n```typescript\nfunction layoutThrashing(element: HTMLElement) {\n element.style.width = '100px'\n const width = element.offsetWidth // Forces reflow\n element.style.height = '200px'\n const height = element.offsetHeight // Forces another reflow\n}\n```\n\n**Correct (batch writes, then read once):**\n```typescript\nfunction updateElementStyles(element: HTMLElement) {\n // Batch all writes together\n element.style.width = '100px'\n element.style.height = '200px'\n element.style.backgroundColor = 'blue'\n element.style.border = '1px solid black'\n \n // Read after all writes are done (single reflow)\n const { width, height } = element.getBoundingClientRect()\n}\n```\n\n**Correct (batch reads, then writes):**\n```typescript\nfunction avoidThrashing(element: HTMLElement) {\n // Read phase - all layout queries first\n const rect1 = element.getBoundingClientRect()\n const offsetWidth = element.offsetWidth\n const offsetHeight = element.offsetHeight\n \n // Write phase - all style changes after\n element.style.width = '100px'\n element.style.height = '200px'\n}\n```\n\n**Better: use CSS classes**\n```css\n.highlighted-box {\n width: 100px;\n height: 200px;\n background-color: blue;\n border: 1px solid black;\n}\n```\n```typescript\nfunction updateElementStyles(element: HTMLElement) {\n element.classList.add('highlighted-box')\n \n const { width, height } = element.getBoundingClientRect()\n}\n```\n\n**React example:**\n```tsx\n// Incorrect: interleaving style changes with layout queries\nfunction Box({ isHighlighted }: { isHighlighted: boolean }) {\n const ref = useRef(null)\n \n useEffect(() => {\n if (ref.current && isHighlighted) {\n ref.current.style.width = '100px'\n const width = ref.current.offsetWidth // Forces layout\n ref.current.style.height = '200px'\n }\n }, [isHighlighted])\n \n return
Content
\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",".agents/skills/vercel-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```\n\n**Correct (cached results):**\n\n```typescript\n// Module-level cache\nconst slugifyCache = new Map()\n\nfunction cachedSlugify(text: string): string {\n if (slugifyCache.has(text)) {\n return slugifyCache.get(text)!\n }\n const result = slugify(text)\n slugifyCache.set(text, result)\n return result\n}\n\nfunction ProjectList({ projects }: { projects: Project[] }) {\n return (\n
\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```\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",".agents/skills/vercel-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",".agents/skills/vercel-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\nfunction getLocalStorage(key: string) {\n if (!storageCache.has(key)) {\n storageCache.set(key, localStorage.getItem(key))\n }\n return storageCache.get(key)\n}\n\nfunction setLocalStorage(key: string, value: string) {\n localStorage.setItem(key, value)\n storageCache.set(key, value) // keep cache in sync\n}\n```\n\nUse a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.\n\n**Cookie caching:**\n\n```typescript\nlet cookieCache: Record | null = null\n\nfunction getCookie(name: string) {\n if (!cookieCache) {\n cookieCache = Object.fromEntries(\n document.cookie.split('; ').map(c => c.split('='))\n )\n }\n return cookieCache[name]\n}\n```\n\n**Important (invalidate on external changes):**\n\nIf storage can change externally (another tab, server-set cookies), invalidate cache:\n\n```typescript\nwindow.addEventListener('storage', (e) => {\n if (e.key) storageCache.delete(e.key)\n})\n\ndocument.addEventListener('visibilitychange', () => {\n if (document.visibilityState === 'visible') {\n storageCache.clear()\n }\n})\n```\n",".agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md":"---\ntitle: Combine Multiple Array Iterations\nimpact: LOW-MEDIUM\nimpactDescription: reduces iterations\ntags: javascript, arrays, loops, performance\n---\n\n## Combine Multiple Array Iterations\n\nMultiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.\n\n**Incorrect (3 iterations):**\n\n```typescript\nconst admins = users.filter(u => u.isAdmin)\nconst testers = users.filter(u => u.isTester)\nconst inactive = users.filter(u => !u.isActive)\n```\n\n**Correct (1 iteration):**\n\n```typescript\nconst admins: User[] = []\nconst testers: User[] = []\nconst inactive: User[] = []\n\nfor (const user of users) {\n if (user.isAdmin) admins.push(user)\n if (user.isTester) testers.push(user)\n if (!user.isActive) inactive.push(user)\n}\n```\n",".agents/skills/vercel-react-best-practices/rules/js-early-exit.md":"---\ntitle: Early Return from Functions\nimpact: LOW-MEDIUM\nimpactDescription: avoids unnecessary computation\ntags: javascript, functions, optimization, early-return\n---\n\n## Early Return from Functions\n\nReturn early when result is determined to skip unnecessary processing.\n\n**Incorrect (processes all items even after finding answer):**\n\n```typescript\nfunction validateUsers(users: User[]) {\n let hasError = false\n let errorMessage = ''\n \n for (const user of users) {\n if (!user.email) {\n hasError = true\n errorMessage = 'Email required'\n }\n if (!user.name) {\n hasError = true\n errorMessage = 'Name required'\n }\n // Continues checking all users even after error found\n }\n \n return hasError ? { valid: false, error: errorMessage } : { valid: true }\n}\n```\n\n**Correct (returns immediately on first error):**\n\n```typescript\nfunction validateUsers(users: User[]) {\n for (const user of users) {\n if (!user.email) {\n return { valid: false, error: 'Email required' }\n }\n if (!user.name) {\n return { valid: false, error: 'Name required' }\n }\n }\n\n return { valid: true }\n}\n```\n",".agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md":"---\ntitle: Use flatMap to Map and Filter in One Pass\nimpact: LOW-MEDIUM\nimpactDescription: eliminates intermediate array\ntags: javascript, arrays, flatMap, filter, performance\n---\n\n## Use flatMap to Map and Filter in One Pass\n\n**Impact: LOW-MEDIUM (eliminates intermediate array)**\n\nChaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.\n\n**Incorrect (2 iterations, intermediate array):**\n\n```typescript\nconst userNames = users\n .map(user => user.isActive ? user.name : null)\n .filter(Boolean)\n```\n\n**Correct (1 iteration, no intermediate array):**\n\n```typescript\nconst userNames = users.flatMap(user =>\n user.isActive ? [user.name] : []\n)\n```\n\n**More examples:**\n\n```typescript\n// Extract valid emails from responses\n// Before\nconst emails = responses\n .map(r => r.success ? r.data.email : null)\n .filter(Boolean)\n\n// After\nconst emails = responses.flatMap(r =>\n r.success ? [r.data.email] : []\n)\n\n// Parse and filter valid numbers\n// Before\nconst numbers = strings\n .map(s => parseInt(s, 10))\n .filter(n => !isNaN(n))\n\n// After\nconst numbers = strings.flatMap(s => {\n const n = parseInt(s, 10)\n return isNaN(n) ? [] : [n]\n})\n```\n\n**When to use:**\n- Transforming items while filtering some out\n- Conditional mapping where some inputs produce no output\n- Parsing/validating where invalid inputs should be skipped\n",".agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md":"---\ntitle: Hoist RegExp Creation\nimpact: LOW-MEDIUM\nimpactDescription: avoids recreation\ntags: javascript, regexp, optimization, memoization\n---\n\n## Hoist RegExp Creation\n\nDon't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.\n\n**Incorrect (new RegExp every render):**\n\n```tsx\nfunction Highlighter({ text, query }: Props) {\n const regex = new RegExp(`(${query})`, 'gi')\n const parts = text.split(regex)\n return <>{parts.map((part, i) => ...)}\n}\n```\n\n**Correct (memoize or hoist):**\n\n```tsx\nconst EMAIL_REGEX = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/\n\nfunction Highlighter({ text, query }: Props) {\n const regex = useMemo(\n () => new RegExp(`(${escapeRegex(query)})`, 'gi'),\n [query]\n )\n const parts = text.split(regex)\n return <>{parts.map((part, i) => ...)}\n}\n```\n\n**Warning (global regex has mutable state):**\n\nGlobal regex (`/g`) has mutable `lastIndex` state:\n\n```typescript\nconst regex = /foo/g\nregex.test('foo') // true, lastIndex = 3\nregex.test('foo') // false, lastIndex = 0\n```\n",".agents/skills/vercel-react-best-practices/rules/js-index-maps.md":"---\ntitle: Build Index Maps for Repeated Lookups\nimpact: LOW-MEDIUM\nimpactDescription: 1M ops to 2K ops\ntags: javascript, map, indexing, optimization, performance\n---\n\n## Build Index Maps for Repeated Lookups\n\nMultiple `.find()` calls by the same key should use a Map.\n\n**Incorrect (O(n) per lookup):**\n\n```typescript\nfunction processOrders(orders: Order[], users: User[]) {\n return orders.map(order => ({\n ...order,\n user: users.find(u => u.id === order.userId)\n }))\n}\n```\n\n**Correct (O(1) per lookup):**\n\n```typescript\nfunction processOrders(orders: Order[], users: User[]) {\n const userById = new Map(users.map(u => [u.id, u]))\n\n return orders.map(order => ({\n ...order,\n user: userById.get(order.userId)\n }))\n}\n```\n\nBuild map once (O(n)), then all lookups are O(1).\nFor 1000 orders × 1000 users: 1M ops → 2K ops.\n",".agents/skills/vercel-react-best-practices/rules/js-length-check-first.md":"---\ntitle: Early Length Check for Array Comparisons\nimpact: MEDIUM-HIGH\nimpactDescription: avoids expensive operations when lengths differ\ntags: javascript, arrays, performance, optimization, comparison\n---\n\n## Early Length Check for Array Comparisons\n\nWhen comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.\n\nIn real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).\n\n**Incorrect (always runs expensive comparison):**\n\n```typescript\nfunction hasChanges(current: string[], original: string[]) {\n // Always sorts and joins, even when lengths differ\n return current.sort().join() !== original.sort().join()\n}\n```\n\nTwo 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.\n\n**Correct (O(1) length check first):**\n\n```typescript\nfunction hasChanges(current: string[], original: string[]) {\n // Early return if lengths differ\n if (current.length !== original.length) {\n return true\n }\n // Only sort when lengths match\n const currentSorted = current.toSorted()\n const originalSorted = original.toSorted()\n for (let i = 0; i < currentSorted.length; i++) {\n if (currentSorted[i] !== originalSorted[i]) {\n return true\n }\n }\n return false\n}\n```\n\nThis new approach is more efficient because:\n- It avoids the overhead of sorting and joining the arrays when lengths differ\n- It avoids consuming memory for the joined strings (especially important for large arrays)\n- It avoids mutating the original arrays\n- It returns early when a difference is found\n",".agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md":"---\ntitle: Use Loop for Min/Max Instead of Sort\nimpact: LOW\nimpactDescription: O(n) instead of O(n log n)\ntags: javascript, arrays, performance, sorting, algorithms\n---\n\n## Use Loop for Min/Max Instead of Sort\n\nFinding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.\n\n**Incorrect (O(n log n) - sort to find latest):**\n\n```typescript\ninterface Project {\n id: string\n name: string\n updatedAt: number\n}\n\nfunction getLatestProject(projects: Project[]) {\n const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)\n return sorted[0]\n}\n```\n\nSorts the entire array just to find the maximum value.\n\n**Incorrect (O(n log n) - sort for oldest and newest):**\n\n```typescript\nfunction getOldestAndNewest(projects: Project[]) {\n const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)\n return { oldest: sorted[0], newest: sorted[sorted.length - 1] }\n}\n```\n\nStill sorts unnecessarily when only min/max are needed.\n\n**Correct (O(n) - single loop):**\n\n```typescript\nfunction getLatestProject(projects: Project[]) {\n if (projects.length === 0) return null\n \n let latest = projects[0]\n \n for (let i = 1; i < projects.length; i++) {\n if (projects[i].updatedAt > latest.updatedAt) {\n latest = projects[i]\n }\n }\n \n return latest\n}\n\nfunction getOldestAndNewest(projects: Project[]) {\n if (projects.length === 0) return { oldest: null, newest: null }\n \n let oldest = projects[0]\n let newest = projects[0]\n \n for (let i = 1; i < projects.length; i++) {\n if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]\n if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]\n }\n \n return { oldest, newest }\n}\n```\n\nSingle pass through the array, no copying, no sorting.\n\n**Alternative (Math.min/Math.max for small arrays):**\n\n```typescript\nconst numbers = [5, 2, 8, 1, 9]\nconst min = Math.min(...numbers)\nconst max = Math.max(...numbers)\n```\n\nThis 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.\n",".agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md":"---\ntitle: Defer Non-Critical Work with requestIdleCallback\nimpact: MEDIUM\nimpactDescription: keeps UI responsive during background tasks\ntags: javascript, performance, idle, scheduling, analytics\n---\n\n## Defer Non-Critical Work with requestIdleCallback\n\n**Impact: MEDIUM (keeps UI responsive during background tasks)**\n\nUse `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.\n\n**Incorrect (blocks main thread during user interaction):**\n\n```typescript\nfunction handleSearch(query: string) {\n const results = searchItems(query)\n setResults(results)\n\n // These block the main thread immediately\n analytics.track('search', { query })\n saveToRecentSearches(query)\n prefetchTopResults(results.slice(0, 3))\n}\n```\n\n**Correct (defers non-critical work to idle time):**\n\n```typescript\nfunction handleSearch(query: string) {\n const results = searchItems(query)\n setResults(results)\n\n // Defer non-critical work to idle periods\n requestIdleCallback(() => {\n analytics.track('search', { query })\n })\n\n requestIdleCallback(() => {\n saveToRecentSearches(query)\n })\n\n requestIdleCallback(() => {\n prefetchTopResults(results.slice(0, 3))\n })\n}\n```\n\n**With timeout for required work:**\n\n```typescript\n// Ensure analytics fires within 2 seconds even if browser stays busy\nrequestIdleCallback(\n () => analytics.track('page_view', { path: location.pathname }),\n { timeout: 2000 }\n)\n```\n\n**Chunking large tasks:**\n\n```typescript\nfunction processLargeDataset(items: Item[]) {\n let index = 0\n\n function processChunk(deadline: IdleDeadline) {\n // Process items while we have idle time (aim for <50ms chunks)\n while (index < items.length && deadline.timeRemaining() > 0) {\n processItem(items[index])\n index++\n }\n\n // Schedule next chunk if more items remain\n if (index < items.length) {\n requestIdleCallback(processChunk)\n }\n }\n\n requestIdleCallback(processChunk)\n}\n```\n\n**With fallback for unsupported browsers:**\n\n```typescript\nconst scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))\n\nscheduleIdleWork(() => {\n // Non-critical work\n})\n```\n\n**When to use:**\n\n- Analytics and telemetry\n- Saving state to localStorage/IndexedDB\n- Prefetching resources for likely next actions\n- Processing non-urgent data transformations\n- Lazy initialization of non-critical features\n\n**When NOT to use:**\n\n- User-initiated actions that need immediate feedback\n- Rendering updates the user is waiting for\n- Time-sensitive operations\n",".agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md":"---\ntitle: Use Set/Map for O(1) Lookups\nimpact: LOW-MEDIUM\nimpactDescription: O(n) to O(1)\ntags: javascript, set, map, data-structures, performance\n---\n\n## Use Set/Map for O(1) Lookups\n\nConvert arrays to Set/Map for repeated membership checks.\n\n**Incorrect (O(n) per check):**\n\n```typescript\nconst allowedIds = ['a', 'b', 'c', ...]\nitems.filter(item => allowedIds.includes(item.id))\n```\n\n**Correct (O(1) per check):**\n\n```typescript\nconst allowedIds = new Set(['a', 'b', 'c', ...])\nitems.filter(item => allowedIds.has(item.id))\n```\n",".agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md":"---\ntitle: Use toSorted() Instead of sort() for Immutability\nimpact: MEDIUM-HIGH\nimpactDescription: prevents mutation bugs in React state\ntags: javascript, arrays, immutability, react, state, mutation\n---\n\n## Use toSorted() Instead of sort() for Immutability\n\n`.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.\n\n**Incorrect (mutates original array):**\n\n```typescript\nfunction UserList({ users }: { users: User[] }) {\n // Mutates the users prop array!\n const sorted = useMemo(\n () => users.sort((a, b) => a.name.localeCompare(b.name)),\n [users]\n )\n return
{sorted.map(renderUser)}
\n}\n```\n\n**Correct (creates new array):**\n\n```typescript\nfunction UserList({ users }: { users: User[] }) {\n // Creates new sorted array, original unchanged\n const sorted = useMemo(\n () => users.toSorted((a, b) => a.name.localeCompare(b.name)),\n [users]\n )\n return
{sorted.map(renderUser)}
\n}\n```\n\n**Why this matters in React:**\n\n1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only\n2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior\n\n**Browser support (fallback for older browsers):**\n\n`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:\n\n```typescript\n// Fallback for older browsers\nconst sorted = [...items].sort((a, b) => a.value - b.value)\n```\n\n**Other immutable array methods:**\n\n- `.toSorted()` - immutable sort\n- `.toReversed()` - immutable reverse\n- `.toSpliced()` - immutable splice\n- `.with()` - immutable element replacement\n",".agents/skills/vercel-react-best-practices/rules/rendering-activity.md":"---\ntitle: Use Activity Component for Show/Hide\nimpact: MEDIUM\nimpactDescription: preserves state/DOM\ntags: rendering, activity, visibility, state-preservation\n---\n\n## Use Activity Component for Show/Hide\n\nUse React's `` to preserve state/DOM for expensive components that frequently toggle visibility.\n\n**Usage:**\n\n```tsx\nimport { Activity } from 'react'\n\nfunction Dropdown({ isOpen }: Props) {\n return (\n \n \n \n )\n}\n```\n\nAvoids expensive re-renders and state loss.\n",".agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md":"---\ntitle: Animate SVG Wrapper Instead of SVG Element\nimpact: LOW\nimpactDescription: enables hardware acceleration\ntags: rendering, svg, css, animation, performance\n---\n\n## Animate SVG Wrapper Instead of SVG Element\n\nMany browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `
` and animate the wrapper instead.\n\n**Incorrect (animating SVG directly - no hardware acceleration):**\n\n```tsx\nfunction LoadingSpinner() {\n return (\n \n \n \n )\n}\n```\n\n**Correct (animating wrapper div - hardware accelerated):**\n\n```tsx\nfunction LoadingSpinner() {\n return (\n
\n \n \n \n
\n )\n}\n```\n\nThis applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.\n",".agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md":"---\ntitle: Use Explicit Conditional Rendering\nimpact: LOW\nimpactDescription: prevents rendering 0 or NaN\ntags: rendering, conditional, jsx, falsy-values\n---\n\n## Use Explicit Conditional Rendering\n\nUse explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.\n\n**Incorrect (renders \"0\" when count is 0):**\n\n```tsx\nfunction Badge({ count }: { count: number }) {\n return (\n
\n {count && {count}}\n
\n )\n}\n\n// When count = 0, renders:
0
\n// When count = 5, renders:
5
\n```\n\n**Correct (renders nothing when count is 0):**\n\n```tsx\nfunction Badge({ count }: { count: number }) {\n return (\n
\n {count > 0 ? {count} : null}\n
\n )\n}\n\n// When count = 0, renders:
\n// When count = 5, renders:
5
\n```\n",".agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md":"---\ntitle: CSS content-visibility for Long Lists\nimpact: HIGH\nimpactDescription: faster initial render\ntags: rendering, css, content-visibility, long-lists\n---\n\n## CSS content-visibility for Long Lists\n\nApply `content-visibility: auto` to defer off-screen rendering.\n\n**CSS:**\n\n```css\n.message-item {\n content-visibility: auto;\n contain-intrinsic-size: 0 80px;\n}\n```\n\n**Example:**\n\n```tsx\nfunction MessageList({ messages }: { messages: Message[] }) {\n return (\n
\n {messages.map(msg => (\n
\n \n
{msg.content}
\n
\n ))}\n
\n )\n}\n```\n\nFor 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).\n",".agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md":"---\ntitle: Hoist Static JSX Elements\nimpact: LOW\nimpactDescription: avoids re-creation\ntags: rendering, jsx, static, optimization\n---\n\n## Hoist Static JSX Elements\n\nExtract static JSX outside components to avoid re-creation.\n\n**Incorrect (recreates element every render):**\n\n```tsx\nfunction LoadingSkeleton() {\n return
\n}\n\nfunction Container() {\n return (\n
\n {loading && }\n
\n )\n}\n```\n\n**Correct (reuses same element):**\n\n```tsx\nconst loadingSkeleton = (\n
\n)\n\nfunction Container() {\n return (\n
\n {loading && loadingSkeleton}\n
\n )\n}\n```\n\nThis is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.\n\n**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.\n",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md":"---\ntitle: Prevent Hydration Mismatch Without Flickering\nimpact: MEDIUM\nimpactDescription: avoids visual flicker and hydration errors\ntags: rendering, ssr, hydration, localStorage, flicker\n---\n\n## Prevent Hydration Mismatch Without Flickering\n\nWhen 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.\n\n**Incorrect (breaks SSR):**\n\n```tsx\nfunction ThemeWrapper({ children }: { children: ReactNode }) {\n // localStorage is not available on server - throws error\n const theme = localStorage.getItem('theme') || 'light'\n \n return (\n
\n {children}\n
\n )\n}\n```\n\nServer-side rendering will fail because `localStorage` is undefined.\n\n**Incorrect (visual flickering):**\n\n```tsx\nfunction ThemeWrapper({ children }: { children: ReactNode }) {\n const [theme, setTheme] = useState('light')\n \n useEffect(() => {\n // Runs after hydration - causes visible flash\n const stored = localStorage.getItem('theme')\n if (stored) {\n setTheme(stored)\n }\n }, [])\n \n return (\n
\n {children}\n
\n )\n}\n```\n\nComponent first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.\n\n**Correct (no flicker, no hydration mismatch):**\n\n```tsx\nfunction ThemeWrapper({ children }: { children: ReactNode }) {\n return (\n <>\n
\n {children}\n
\n \n \n )\n}\n```\n\nThe inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.\n\nThis pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.\n",".agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md":"---\ntitle: Suppress Expected Hydration Mismatches\nimpact: LOW-MEDIUM\nimpactDescription: avoids noisy hydration warnings for known differences\ntags: rendering, hydration, ssr, nextjs\n---\n\n## Suppress Expected Hydration Mismatches\n\nIn 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.\n\n**Incorrect (known mismatch warnings):**\n\n```tsx\nfunction Timestamp() {\n return {new Date().toLocaleString()}\n}\n```\n\n**Correct (suppress expected mismatch only):**\n\n```tsx\nfunction Timestamp() {\n return (\n \n {new Date().toLocaleString()}\n \n )\n}\n```\n",".agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md":"---\ntitle: Use React DOM Resource Hints\nimpact: HIGH\nimpactDescription: reduces load time for critical resources\ntags: rendering, preload, preconnect, prefetch, resource-hints\n---\n\n## Use React DOM Resource Hints\n\n**Impact: HIGH (reduces load time for critical resources)**\n\nReact 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.\n\n- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to\n- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server\n- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon\n- **`preloadModule(href)`**: Fetch an ES module you'll use soon\n- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script\n- **`preinitModule(href)`**: Fetch and evaluate an ES module\n\n**Example (preconnect to third-party APIs):**\n\n```tsx\nimport { preconnect, prefetchDNS } from 'react-dom'\n\nexport default function App() {\n prefetchDNS('https://analytics.example.com')\n preconnect('https://api.example.com')\n\n return
{/* content */}
\n}\n```\n\n**Example (preload critical fonts and styles):**\n\n```tsx\nimport { preload, preinit } from 'react-dom'\n\nexport default function RootLayout({ children }) {\n // Preload font file\n preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })\n\n // Fetch and apply critical stylesheet immediately\n preinit('/styles/critical.css', { as: 'style' })\n\n return (\n \n {children}\n \n )\n}\n```\n\n**Example (preload modules for code-split routes):**\n\n```tsx\nimport { preloadModule, preinitModule } from 'react-dom'\n\nfunction Navigation() {\n const preloadDashboard = () => {\n preloadModule('/dashboard.js', { as: 'script' })\n }\n\n return (\n \n )\n}\n```\n\n**When to use each:**\n\n| API | Use case |\n|-----|----------|\n| `prefetchDNS` | Third-party domains you'll connect to later |\n| `preconnect` | APIs or CDNs you'll fetch from immediately |\n| `preload` | Critical resources needed for current page |\n| `preloadModule` | JS modules for likely next navigation |\n| `preinit` | Stylesheets/scripts that must execute early |\n| `preinitModule` | ES modules that must execute early |\n\nReference: [React DOM Resource Preloading APIs](https://react.dev/reference/react-dom#resource-preloading-apis)\n",".agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md":"---\ntitle: Use defer or async on Script Tags\nimpact: HIGH\nimpactDescription: eliminates render-blocking\ntags: rendering, script, defer, async, performance\n---\n\n## Use defer or async on Script Tags\n\n**Impact: HIGH (eliminates render-blocking)**\n\nScript tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.\n\n- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order\n- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order\n\nUse `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.\n\n**Incorrect (blocks rendering):**\n\n```tsx\nexport default function Document() {\n return (\n \n \n