Showing preview only (585K chars total). Download the full file or copy to clipboard to get everything.
Repository: vercel-labs/agent-skills
Branch: main
Commit: 9aec8ee6aaf7
Files: 146
Total size: 542.0 KB
Directory structure:
gitextract_uut7bmea/
├── .github/
│ └── workflows/
│ └── react-best-practices-ci.yml
├── .gitignore
├── AGENTS.md
├── README.md
├── packages/
│ └── react-best-practices-build/
│ ├── .gitignore
│ ├── package.json
│ ├── src/
│ │ ├── build.ts
│ │ ├── config.ts
│ │ ├── extract-tests.ts
│ │ ├── migrate.ts
│ │ ├── parser.ts
│ │ ├── types.ts
│ │ └── validate.ts
│ ├── test-cases.json
│ └── tsconfig.json
└── skills/
├── composition-patterns/
│ ├── AGENTS.md
│ ├── README.md
│ ├── SKILL.md
│ ├── metadata.json
│ └── rules/
│ ├── _sections.md
│ ├── _template.md
│ ├── architecture-avoid-boolean-props.md
│ ├── architecture-compound-components.md
│ ├── patterns-children-over-render-props.md
│ ├── patterns-explicit-variants.md
│ ├── react19-no-forwardref.md
│ ├── state-context-interface.md
│ ├── state-decouple-implementation.md
│ └── state-lift-state.md
├── deploy-to-vercel/
│ ├── SKILL.md
│ └── resources/
│ ├── deploy-codex.sh
│ └── deploy.sh
├── react-best-practices/
│ ├── AGENTS.md
│ ├── README.md
│ ├── SKILL.md
│ ├── metadata.json
│ └── rules/
│ ├── _sections.md
│ ├── _template.md
│ ├── advanced-event-handler-refs.md
│ ├── advanced-init-once.md
│ ├── advanced-use-latest.md
│ ├── async-api-routes.md
│ ├── async-defer-await.md
│ ├── async-dependencies.md
│ ├── async-parallel.md
│ ├── async-suspense-boundaries.md
│ ├── bundle-barrel-imports.md
│ ├── bundle-conditional.md
│ ├── bundle-defer-third-party.md
│ ├── bundle-dynamic-imports.md
│ ├── bundle-preload.md
│ ├── client-event-listeners.md
│ ├── client-localstorage-schema.md
│ ├── client-passive-event-listeners.md
│ ├── client-swr-dedup.md
│ ├── js-batch-dom-css.md
│ ├── js-cache-function-results.md
│ ├── js-cache-property-access.md
│ ├── js-cache-storage.md
│ ├── js-combine-iterations.md
│ ├── js-early-exit.md
│ ├── js-flatmap-filter.md
│ ├── js-hoist-regexp.md
│ ├── js-index-maps.md
│ ├── js-length-check-first.md
│ ├── js-min-max-loop.md
│ ├── js-set-map-lookups.md
│ ├── js-tosorted-immutable.md
│ ├── rendering-activity.md
│ ├── rendering-animate-svg-wrapper.md
│ ├── rendering-conditional-render.md
│ ├── rendering-content-visibility.md
│ ├── rendering-hoist-jsx.md
│ ├── rendering-hydration-no-flicker.md
│ ├── rendering-hydration-suppress-warning.md
│ ├── rendering-resource-hints.md
│ ├── rendering-script-defer-async.md
│ ├── rendering-svg-precision.md
│ ├── rendering-usetransition-loading.md
│ ├── rerender-defer-reads.md
│ ├── rerender-dependencies.md
│ ├── rerender-derived-state-no-effect.md
│ ├── rerender-derived-state.md
│ ├── rerender-functional-setstate.md
│ ├── rerender-lazy-state-init.md
│ ├── rerender-memo-with-default-value.md
│ ├── rerender-memo.md
│ ├── rerender-move-effect-to-event.md
│ ├── rerender-no-inline-components.md
│ ├── rerender-simple-expression-in-memo.md
│ ├── rerender-split-combined-hooks.md
│ ├── rerender-transitions.md
│ ├── rerender-use-deferred-value.md
│ ├── rerender-use-ref-transient-values.md
│ ├── server-after-nonblocking.md
│ ├── server-auth-actions.md
│ ├── server-cache-lru.md
│ ├── server-cache-react.md
│ ├── server-dedup-props.md
│ ├── server-hoist-static-io.md
│ ├── server-parallel-fetching.md
│ └── server-serialization.md
├── react-native-skills/
│ ├── AGENTS.md
│ ├── README.md
│ ├── SKILL.md
│ ├── metadata.json
│ └── rules/
│ ├── _sections.md
│ ├── _template.md
│ ├── animation-derived-value.md
│ ├── animation-gesture-detector-press.md
│ ├── animation-gpu-properties.md
│ ├── design-system-compound-components.md
│ ├── fonts-config-plugin.md
│ ├── imports-design-system-folder.md
│ ├── js-hoist-intl.md
│ ├── list-performance-callbacks.md
│ ├── list-performance-function-references.md
│ ├── list-performance-images.md
│ ├── list-performance-inline-objects.md
│ ├── list-performance-item-expensive.md
│ ├── list-performance-item-memo.md
│ ├── list-performance-item-types.md
│ ├── list-performance-virtualize.md
│ ├── monorepo-native-deps-in-app.md
│ ├── monorepo-single-dependency-versions.md
│ ├── navigation-native-navigators.md
│ ├── react-compiler-destructure-functions.md
│ ├── react-compiler-reanimated-shared-values.md
│ ├── react-state-dispatcher.md
│ ├── react-state-fallback.md
│ ├── react-state-minimize.md
│ ├── rendering-no-falsy-and.md
│ ├── rendering-text-in-text-component.md
│ ├── scroll-position-no-state.md
│ ├── state-ground-truth.md
│ ├── ui-expo-image.md
│ ├── ui-image-gallery.md
│ ├── ui-measure-views.md
│ ├── ui-menus.md
│ ├── ui-native-modals.md
│ ├── ui-pressable.md
│ ├── ui-safe-area-scroll.md
│ ├── ui-scrollview-content-inset.md
│ └── ui-styling.md
├── vercel-cli-with-tokens/
│ └── SKILL.md
└── web-design-guidelines/
└── SKILL.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/workflows/react-best-practices-ci.yml
================================================
name: React Best Practices CI
on:
push:
branches: [main]
paths:
- 'skills/react-best-practices/**'
- 'packages/react-best-practices-build/**'
pull_request:
branches: [main]
paths:
- 'skills/react-best-practices/**'
- 'packages/react-best-practices-build/**'
jobs:
validate:
runs-on: ubuntu-latest
defaults:
run:
working-directory: packages/react-best-practices-build
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v2
with:
version: 10.24.0
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'pnpm'
cache-dependency-path: packages/react-best-practices-build/pnpm-lock.yaml
- run: pnpm install
- run: pnpm validate
- run: pnpm build
================================================
FILE: .gitignore
================================================
.DS_Store
.vercel
.env*.local
================================================
FILE: AGENTS.md
================================================
# AGENTS.md
This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.
## Repository Overview
A collection of skills for Claude.ai and Claude Code for working with Vercel deployments. Skills are packaged instructions and scripts that extend Claude's capabilities.
## Creating a New Skill
### Directory Structure
```
skills/
{skill-name}/ # kebab-case directory name
SKILL.md # Required: skill definition
scripts/ # Required: executable scripts
{script-name}.sh # Bash scripts (preferred)
{skill-name}.zip # Required: packaged for distribution
```
### Naming Conventions
- **Skill directory**: `kebab-case` (e.g., `vercel-deploy`, `log-monitor`)
- **SKILL.md**: Always uppercase, always this exact filename
- **Scripts**: `kebab-case.sh` (e.g., `deploy.sh`, `fetch-logs.sh`)
- **Zip file**: Must match directory name exactly: `{skill-name}.zip`
### SKILL.md Format
```markdown
---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases like "Deploy my app", "Check logs", etc.}
---
# {Skill Title}
{Brief description of what the skill does.}
## How It Works
{Numbered list explaining the skill's workflow}
## Usage
```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]
```
**Arguments:**
- `arg1` - Description (defaults to X)
**Examples:**
{Show 2-3 common usage patterns}
## Output
{Show example output users will see}
## Present Results to User
{Template for how Claude should format results when presenting to users}
## Troubleshooting
{Common issues and solutions, especially network/permissions errors}
```
### Best Practices for Context Efficiency
Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:
- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
- **Write specific descriptions** — helps the agent know exactly when to activate the skill
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files
### Script Requirements
- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`
### Creating the Zip Package
After creating or updating a skill:
```bash
cd skills
zip -r {skill-name}.zip {skill-name}/
```
### End-User Installation
Document these two installation methods for users:
**Claude Code:**
```bash
cp -r skills/{skill-name} ~/.claude/skills/
```
**claude.ai:**
Add the skill to project knowledge or paste SKILL.md contents into the conversation.
If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
================================================
FILE: README.md
================================================
# Agent Skills
A collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities.
Skills follow the [Agent Skills](https://agentskills.io/) format.
## Available Skills
### react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. Contains 40+ rules across 8 categories, prioritized by impact.
**Use when:**
- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Reviewing code for performance issues
- Optimizing bundle size or load times
**Categories covered:**
- Eliminating waterfalls (Critical)
- Bundle size optimization (Critical)
- Server-side performance (High)
- Client-side data fetching (Medium-High)
- Re-render optimization (Medium)
- Rendering performance (Medium)
- JavaScript micro-optimizations (Low-Medium)
### web-design-guidelines
Review UI code for compliance with web interface best practices. Audits your code for 100+ rules covering accessibility, performance, and UX.
**Use when:**
- "Review my UI"
- "Check accessibility"
- "Audit design"
- "Review UX"
- "Check my site against best practices"
**Categories covered:**
- Accessibility (aria-labels, semantic HTML, keyboard handlers)
- Focus States (visible focus, focus-visible patterns)
- Forms (autocomplete, validation, error handling)
- Animation (prefers-reduced-motion, compositor-friendly transforms)
- Typography (curly quotes, ellipsis, tabular-nums)
- Images (dimensions, lazy loading, alt text)
- Performance (virtualization, layout thrashing, preconnect)
- Navigation & State (URL reflects state, deep-linking)
- Dark Mode & Theming (color-scheme, theme-color meta)
- Touch & Interaction (touch-action, tap-highlight)
- Locale & i18n (Intl.DateTimeFormat, Intl.NumberFormat)
### react-native-guidelines
React Native best practices optimized for AI agents. Contains 16 rules across 7 sections covering performance, architecture, and platform-specific patterns.
**Use when:**
- Building React Native or Expo apps
- Optimizing mobile performance
- Implementing animations or gestures
- Working with native modules or platform APIs
**Categories covered:**
- Performance (Critical) - FlashList, memoization, heavy computation
- Layout (High) - flex patterns, safe areas, keyboard handling
- Animation (High) - Reanimated, gesture handling
- Images (Medium) - expo-image, caching, lazy loading
- State Management (Medium) - Zustand patterns, React Compiler
- Architecture (Medium) - monorepo structure, imports
- Platform (Medium) - iOS/Android specific patterns
### composition-patterns
React composition patterns that scale. Helps avoid boolean prop proliferation through compound components, state lifting, and internal composition.
**Use when:**
- Refactoring components with many boolean props
- Building reusable component libraries
- Designing flexible APIs
- Reviewing component architecture
**Patterns covered:**
- Extracting compound components
- Lifting state to reduce props
- Composing internals for flexibility
- Avoiding prop drilling
### vercel-deploy-claimable
Deploy applications and websites to Vercel instantly. Designed for use with claude.ai and Claude Desktop to enable deployments directly from conversations. Deployments are "claimable" - users can transfer ownership to their own Vercel account.
**Use when:**
- "Deploy my app"
- "Deploy this to production"
- "Push this live"
- "Deploy and give me the link"
**Features:**
- Auto-detects 40+ frameworks from `package.json`
- Returns preview URL (live site) and claim URL (transfer ownership)
- Handles static HTML projects automatically
- Excludes `node_modules` and `.git` from uploads
**How it works:**
1. Packages your project into a tarball
2. Detects framework (Next.js, Vite, Astro, etc.)
3. Uploads to deployment service
4. Returns preview URL and claim URL
**Output:**
```
Deployment successful!
Preview URL: https://skill-deploy-abc123.vercel.app
Claim URL: https://vercel.com/claim-deployment?code=...
```
## Installation
```bash
npx skills add vercel-labs/agent-skills
```
## Usage
Skills are automatically available once installed. The agent will use them when relevant tasks are detected.
**Examples:**
```
Deploy my app
```
```
Review this React component for performance issues
```
```
Help me optimize this Next.js page
```
## Skill Structure
Each skill contains:
- `SKILL.md` - Instructions for the agent
- `scripts/` - Helper scripts for automation (optional)
- `references/` - Supporting documentation (optional)
## License
MIT
================================================
FILE: packages/react-best-practices-build/.gitignore
================================================
node_modules/
================================================
FILE: packages/react-best-practices-build/package.json
================================================
{
"name": "react-best-practices-build",
"version": "1.0.0",
"description": "Build tooling for React Best Practices and React Native Guidelines skills",
"type": "module",
"scripts": {
"build": "pnpm build-agents && pnpm extract-tests",
"build-agents": "tsx src/build.ts",
"build-all": "tsx src/build.ts --all",
"build-react": "tsx src/build.ts --skill=react-best-practices",
"build-rn": "tsx src/build.ts --skill=react-native-skills",
"build-composition": "tsx src/build.ts --skill=composition-patterns",
"validate": "tsx src/validate.ts",
"extract-tests": "tsx src/extract-tests.ts",
"migrate": "tsx src/migrate.ts",
"dev": "pnpm build && pnpm validate"
},
"keywords": [
"react",
"performance",
"guidelines",
"llm",
"agents"
],
"license": "MIT",
"devDependencies": {
"@types/node": "^20.0.0",
"tsx": "^4.7.0",
"typescript": "^5.3.0"
}
}
================================================
FILE: packages/react-best-practices-build/src/build.ts
================================================
#!/usr/bin/env node
/**
* Build script to compile individual rule files into AGENTS.md
*/
import { readdir, readFile, writeFile } from 'fs/promises'
import { join } from 'path'
import { Rule, Section, GuidelinesDocument, ImpactLevel } from './types.js'
import { parseRuleFile, RuleFile } from './parser.js'
import { SKILLS, SkillConfig, DEFAULT_SKILL } from './config.js'
// Parse command line arguments
const args = process.argv.slice(2)
const upgradeVersion = args.includes('--upgrade-version')
const skillArg = args.find((arg) => arg.startsWith('--skill='))
const skillName = skillArg ? skillArg.split('=')[1] : null
const buildAll = args.includes('--all')
/**
* Increment a semver-style version string (e.g., "0.1.0" -> "0.1.1", "1.0" -> "1.1")
*/
function incrementVersion(version: string): string {
const parts = version.split('.').map(Number)
// Increment the last part
parts[parts.length - 1]++
return parts.join('.')
}
/**
* Generate markdown from rules
*/
function generateMarkdown(
sections: Section[],
metadata: {
version: string
organization: string
date: string
abstract: string
references?: string[]
},
skillConfig: SkillConfig
): string {
let md = `# ${skillConfig.title}\n\n`
md += `**Version ${metadata.version}** \n`
md += `${metadata.organization} \n`
md += `${metadata.date}\n\n`
md += `> **Note:** \n`
md += `> This document is mainly for agents and LLMs to follow when maintaining, \n`
md += `> generating, or refactoring ${skillConfig.description}. Humans \n`
md += `> may also find it useful, but guidance here is optimized for automation \n`
md += `> and consistency by AI-assisted workflows.\n\n`
md += `---\n\n`
md += `## Abstract\n\n`
md += `${metadata.abstract}\n\n`
md += `---\n\n`
md += `## Table of Contents\n\n`
// Generate TOC
sections.forEach((section) => {
md += `${section.number}. [${section.title}](#${
section.number
}-${section.title.toLowerCase().replace(/\s+/g, '-')}) — **${
section.impact
}**\n`
section.rules.forEach((rule) => {
// GitHub generates anchors from the full heading text: "1.1 Title" -> "#11-title"
const anchor = `${rule.id} ${rule.title}`
.toLowerCase()
.replace(/\s+/g, '-')
.replace(/[^\w-]/g, '') // Remove special characters except hyphens
md += ` - ${rule.id} [${rule.title}](#${anchor})\n`
})
})
md += `\n---\n\n`
// Generate sections
sections.forEach((section) => {
md += `## ${section.number}. ${section.title}\n\n`
md += `**Impact: ${section.impact}${
section.impactDescription ? ` (${section.impactDescription})` : ''
}**\n\n`
if (section.introduction) {
md += `${section.introduction}\n\n`
}
section.rules.forEach((rule) => {
md += `### ${rule.id} ${rule.title}\n\n`
md += `**Impact: ${rule.impact}${
rule.impactDescription ? ` (${rule.impactDescription})` : ''
}**\n\n`
md += `${rule.explanation}\n\n`
rule.examples.forEach((example) => {
if (example.description) {
md += `**${example.label}: ${example.description}**\n\n`
} else {
md += `**${example.label}:**\n\n`
}
// Only generate code block if there's actual code
if (example.code && example.code.trim()) {
md += `\`\`\`${example.language || 'typescript'}\n`
md += `${example.code}\n`
md += `\`\`\`\n\n`
}
if (example.additionalText) {
md += `${example.additionalText}\n\n`
}
})
if (rule.references && rule.references.length > 0) {
md += `Reference: ${rule.references
.map((ref) => `[${ref}](${ref})`)
.join(', ')}\n\n`
}
})
md += `---\n\n`
})
// Add references section
if (metadata.references && metadata.references.length > 0) {
md += `## References\n\n`
metadata.references.forEach((ref, i) => {
md += `${i + 1}. [${ref}](${ref})\n`
})
}
return md
}
/**
* Build a single skill
*/
async function buildSkill(skillConfig: SkillConfig) {
console.log(`\nBuilding ${skillConfig.name}...`)
console.log(` Rules directory: ${skillConfig.rulesDir}`)
console.log(` Output file: ${skillConfig.outputFile}`)
// Read all rule files (exclude files starting with _ and README.md)
const files = await readdir(skillConfig.rulesDir)
const ruleFiles = files
.filter((f) => f.endsWith('.md') && !f.startsWith('_') && f !== 'README.md')
.sort() // Sort filenames for consistent ordering across systems
const ruleData: RuleFile[] = []
for (const file of ruleFiles) {
const filePath = join(skillConfig.rulesDir, file)
try {
const parsed = await parseRuleFile(filePath, skillConfig.sectionMap)
ruleData.push(parsed)
} catch (error) {
console.error(` Error parsing ${file}:`, error)
}
}
// Group rules by section
const sectionsMap = new Map<number, Section>()
ruleData.forEach(({ section, rule }) => {
if (!sectionsMap.has(section)) {
sectionsMap.set(section, {
number: section,
title: `Section ${section}`, // Will be overridden by section metadata
impact: rule.impact,
rules: [],
})
}
sectionsMap.get(section)!.rules.push(rule)
})
// Sort rules within each section by title (using en-US locale for consistency across environments)
sectionsMap.forEach((section) => {
section.rules.sort((a, b) =>
a.title.localeCompare(b.title, 'en-US', { sensitivity: 'base' })
)
// Assign IDs based on sorted order
section.rules.forEach((rule, index) => {
rule.id = `${section.number}.${index + 1}`
rule.subsection = index + 1
})
})
// Convert to array and sort
const sections = Array.from(sectionsMap.values()).sort(
(a, b) => a.number - b.number
)
// Read section metadata from consolidated _sections.md file
const sectionsFile = join(skillConfig.rulesDir, '_sections.md')
try {
const sectionsContent = await readFile(sectionsFile, 'utf-8')
// Parse sections using regex to match each section block
const sectionBlocks = sectionsContent
.split(/(?=^## \d+\. )/m)
.filter(Boolean)
for (const block of sectionBlocks) {
// Extract section number and title, removing section ID in parentheses
const headerMatch = block.match(/^## (\d+)\.\s+(.+?)(?:\s+\([^)]+\))?$/m)
if (!headerMatch) continue
const sectionNumber = parseInt(headerMatch[1])
const sectionTitle = headerMatch[2].trim() // Strip (id) for output
// Extract impact (format: **Impact:** CRITICAL)
const impactMatch = block.match(/\*\*Impact:\*\*\s+(\w+(?:-\w+)?)/i)
const impactLevel = impactMatch
? (impactMatch[1].toUpperCase().replace(/-/g, '-') as ImpactLevel)
: 'MEDIUM'
// Extract description (format: **Description:** text)
const descMatch = block.match(/\*\*Description:\*\*\s+(.+?)(?=\n\n##|$)/s)
const description = descMatch ? descMatch[1].trim() : ''
// Update section if it exists
const section = sections.find((s) => s.number === sectionNumber)
if (section) {
section.title = sectionTitle
section.impact = impactLevel
section.introduction = description
}
}
} catch (error) {
console.warn(' Warning: Could not read _sections.md, using defaults')
}
// Read metadata
let metadata
try {
const metadataContent = await readFile(skillConfig.metadataFile, 'utf-8')
metadata = JSON.parse(metadataContent)
} catch {
metadata = {
version: '1.0.0',
organization: 'Engineering',
date: new Date().toLocaleDateString('en-US', {
month: 'long',
year: 'numeric',
}),
abstract: `Performance optimization guide for ${skillConfig.description}, ordered by impact.`,
}
}
// Upgrade version if flag is passed
if (upgradeVersion) {
const oldVersion = metadata.version
metadata.version = incrementVersion(oldVersion)
console.log(` Upgrading version: ${oldVersion} -> ${metadata.version}`)
// Write updated metadata.json
await writeFile(
skillConfig.metadataFile,
JSON.stringify(metadata, null, 2) + '\n',
'utf-8'
)
console.log(` ✓ Updated metadata.json`)
// Update SKILL.md frontmatter if it exists
const skillFile = join(skillConfig.skillDir, 'SKILL.md')
try {
const skillContent = await readFile(skillFile, 'utf-8')
const updatedSkillContent = skillContent.replace(
/^(---[\s\S]*?version:\s*)"[^"]*"([\s\S]*?---)$/m,
`$1"${metadata.version}"$2`
)
await writeFile(skillFile, updatedSkillContent, 'utf-8')
console.log(` ✓ Updated SKILL.md`)
} catch {
// SKILL.md doesn't exist, skip
}
}
// Generate markdown
const markdown = generateMarkdown(sections, metadata, skillConfig)
// Write output
await writeFile(skillConfig.outputFile, markdown, 'utf-8')
console.log(
` ✓ Built AGENTS.md with ${sections.length} sections and ${ruleData.length} rules`
)
}
/**
* Main build function
*/
async function build() {
try {
console.log('Building AGENTS.md from rules...')
if (buildAll) {
// Build all skills
for (const skill of Object.values(SKILLS)) {
await buildSkill(skill)
}
} else if (skillName) {
// Build specific skill
const skill = SKILLS[skillName]
if (!skill) {
console.error(`Unknown skill: ${skillName}`)
console.error(`Available skills: ${Object.keys(SKILLS).join(', ')}`)
process.exit(1)
}
await buildSkill(skill)
} else {
// Build default skill (backwards compatibility)
await buildSkill(SKILLS[DEFAULT_SKILL])
}
console.log('\n✓ Build complete')
} catch (error) {
console.error('Build failed:', error)
process.exit(1)
}
}
build()
================================================
FILE: packages/react-best-practices-build/src/config.ts
================================================
/**
* Configuration for the build tooling
*/
import { join, dirname } from 'path'
import { fileURLToPath } from 'url'
const __dirname = dirname(fileURLToPath(import.meta.url))
// Base paths
export const SKILLS_DIR = join(__dirname, '../../..', 'skills')
export const BUILD_DIR = join(__dirname, '..')
// Skill configurations
export interface SkillConfig {
name: string
title: string
description: string
skillDir: string
rulesDir: string
metadataFile: string
outputFile: string
sectionMap: Record<string, number>
}
export const SKILLS: Record<string, SkillConfig> = {
'react-best-practices': {
name: 'react-best-practices',
title: 'React Best Practices',
description: 'React and Next.js codebases',
skillDir: join(SKILLS_DIR, 'react-best-practices'),
rulesDir: join(SKILLS_DIR, 'react-best-practices/rules'),
metadataFile: join(SKILLS_DIR, 'react-best-practices/metadata.json'),
outputFile: join(SKILLS_DIR, 'react-best-practices/AGENTS.md'),
sectionMap: {
async: 1,
bundle: 2,
server: 3,
client: 4,
rerender: 5,
rendering: 6,
js: 7,
advanced: 8,
},
},
'react-native-skills': {
name: 'react-native-skills',
title: 'React Native Skills',
description: 'React Native codebases',
skillDir: join(SKILLS_DIR, 'react-native-skills'),
rulesDir: join(SKILLS_DIR, 'react-native-skills/rules'),
metadataFile: join(SKILLS_DIR, 'react-native-skills/metadata.json'),
outputFile: join(SKILLS_DIR, 'react-native-skills/AGENTS.md'),
sectionMap: {
rendering: 1,
'list-performance': 2,
animation: 3,
scroll: 4,
navigation: 5,
'react-state': 6,
state: 7,
'react-compiler': 8,
ui: 9,
'design-system': 10,
monorepo: 11,
imports: 12,
js: 13,
fonts: 14,
},
},
'composition-patterns': {
name: 'composition-patterns',
title: 'React Composition Patterns',
description: 'React codebases using composition',
skillDir: join(SKILLS_DIR, 'composition-patterns'),
rulesDir: join(SKILLS_DIR, 'composition-patterns/rules'),
metadataFile: join(SKILLS_DIR, 'composition-patterns/metadata.json'),
outputFile: join(SKILLS_DIR, 'composition-patterns/AGENTS.md'),
sectionMap: {
architecture: 1,
state: 2,
patterns: 3,
react19: 4,
},
},
}
// Default skill (for backwards compatibility)
export const DEFAULT_SKILL = 'react-best-practices'
// Legacy exports for backwards compatibility
export const SKILL_DIR = SKILLS[DEFAULT_SKILL].skillDir
export const RULES_DIR = SKILLS[DEFAULT_SKILL].rulesDir
export const METADATA_FILE = SKILLS[DEFAULT_SKILL].metadataFile
export const OUTPUT_FILE = SKILLS[DEFAULT_SKILL].outputFile
// Test cases are build artifacts, not part of the skill
export const TEST_CASES_FILE = join(BUILD_DIR, 'test-cases.json')
================================================
FILE: packages/react-best-practices-build/src/extract-tests.ts
================================================
#!/usr/bin/env node
/**
* Extract test cases from rules for LLM evaluation
*/
import { readdir, writeFile } from 'fs/promises'
import { join } from 'path'
import { Rule, TestCase } from './types.js'
import { parseRuleFile } from './parser.js'
import { RULES_DIR, TEST_CASES_FILE } from './config.js'
/**
* Extract test cases from a rule
*/
function extractTestCases(rule: Rule): TestCase[] {
const testCases: TestCase[] = []
rule.examples.forEach((example, index) => {
const isBad = example.label.toLowerCase().includes('incorrect') ||
example.label.toLowerCase().includes('wrong') ||
example.label.toLowerCase().includes('bad')
const isGood = example.label.toLowerCase().includes('correct') ||
example.label.toLowerCase().includes('good')
if (isBad || isGood) {
testCases.push({
ruleId: rule.id,
ruleTitle: rule.title,
type: isBad ? 'bad' : 'good',
code: example.code,
language: example.language || 'typescript',
description: example.description || `${example.label} example for ${rule.title}`
})
}
})
return testCases
}
/**
* Main extraction function
*/
async function extractTests() {
try {
console.log('Extracting test cases from rules...')
console.log(`Rules directory: ${RULES_DIR}`)
console.log(`Output file: ${TEST_CASES_FILE}`)
const files = await readdir(RULES_DIR)
const ruleFiles = files.filter(f => f.endsWith('.md') && !f.startsWith('_') && f !== 'README.md')
const allTestCases: TestCase[] = []
for (const file of ruleFiles) {
const filePath = join(RULES_DIR, file)
try {
const { rule } = await parseRuleFile(filePath)
const testCases = extractTestCases(rule)
allTestCases.push(...testCases)
} catch (error) {
console.error(`Error processing ${file}:`, error)
}
}
// Write test cases as JSON
await writeFile(TEST_CASES_FILE, JSON.stringify(allTestCases, null, 2), 'utf-8')
console.log(`✓ Extracted ${allTestCases.length} test cases to ${TEST_CASES_FILE}`)
console.log(` - Bad examples: ${allTestCases.filter(tc => tc.type === 'bad').length}`)
console.log(` - Good examples: ${allTestCases.filter(tc => tc.type === 'good').length}`)
} catch (error) {
console.error('Extraction failed:', error)
process.exit(1)
}
}
extractTests()
================================================
FILE: packages/react-best-practices-build/src/migrate.ts
================================================
#!/usr/bin/env node
/**
* Migration script to split RPG.md into individual rule files
* This is a one-time script to help migrate existing content
*/
import { readFile, writeFile, mkdir } from 'fs/promises'
import { join } from 'path'
import { existsSync } from 'fs'
import { SKILL_DIR, RULES_DIR } from './config.js'
const RPG_FILE = join(SKILL_DIR, 'RPG.md')
/**
* Extract section number and title from heading
*/
function parseSectionHeading(line: string): { number: number; title: string } | null {
const match = line.match(/^##\s+(\d+)\.\s+(.+)$/)
if (match) {
return {
number: parseInt(match[1]),
title: match[2].trim()
}
}
return null
}
/**
* Extract rule number and title from heading
*/
function parseRuleHeading(line: string): { section: number; subsection: number; title: string } | null {
const match = line.match(/^###\s+(\d+)\.(\d+)\s+(.+)$/)
if (match) {
return {
section: parseInt(match[1]),
subsection: parseInt(match[2]),
title: match[3].trim()
}
}
return null
}
/**
* Extract impact from line
*/
function extractImpact(line: string): { impact: string; description?: string } | null {
const match = line.match(/\*\*Impact:\s*(\w+(?:-\w+)?)\s*(?:\(([^)]+)\))?/i)
if (match) {
return {
impact: match[1].toUpperCase().replace(/-/g, '-'),
description: match[2]
}
}
return null
}
async function migrate() {
try {
console.log('Migrating RPG.md to individual rule files...')
if (!existsSync(RPG_FILE)) {
console.error(`RPG.md not found at ${RPG_FILE}`)
process.exit(1)
}
// Ensure rules directory exists
if (!existsSync(RULES_DIR)) {
await mkdir(RULES_DIR, { recursive: true })
}
const content = await readFile(RPG_FILE, 'utf-8')
const lines = content.split('\n')
let currentSection: { number: number; title: string; impact?: string; introduction?: string } | null = null
let currentRule: { section: number; subsection: number; title: string; content: string[] } | null = null
let inCodeBlock = false
for (let i = 0; i < lines.length; i++) {
const line = lines[i]
// Check for section heading
const sectionInfo = parseSectionHeading(line)
if (sectionInfo) {
// Save previous section if exists
if (currentSection) {
const sectionFile = join(RULES_DIR, `section-${currentSection.number}.md`)
let sectionContent = `# ${currentSection.number}. ${currentSection.title}\n\n`
if (currentSection.impact) {
sectionContent += `**Impact: ${currentSection.impact}**\n\n`
}
if (currentSection.introduction) {
sectionContent += `## Introduction\n\n${currentSection.introduction}\n`
}
await writeFile(sectionFile, sectionContent, 'utf-8')
}
currentSection = sectionInfo
currentRule = null
// Look for impact on next few lines
for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
const impactInfo = extractImpact(lines[j])
if (impactInfo) {
currentSection.impact = impactInfo.impact
break
}
}
// Collect introduction text until first rule
let introduction: string[] = []
for (let j = i + 1; j < lines.length; j++) {
if (parseRuleHeading(lines[j])) {
break
}
if (!lines[j].match(/^###/)) {
introduction.push(lines[j])
}
}
currentSection.introduction = introduction.join('\n').trim()
continue
}
// Check for rule heading
const ruleInfo = parseRuleHeading(line)
if (ruleInfo) {
// Save previous rule if exists
if (currentRule && currentSection) {
const ruleFile = join(RULES_DIR, `section-${currentRule.section}-rule-${currentRule.subsection}.md`)
const ruleContent = currentRule.content.join('\n')
await writeFile(ruleFile, ruleContent, 'utf-8')
console.log(`Created ${ruleFile}`)
}
currentRule = {
...ruleInfo,
content: [line]
}
continue
}
// Accumulate content for current rule
if (currentRule) {
currentRule.content.push(line)
}
}
// Save last rule
if (currentRule && currentSection) {
const ruleFile = join(RULES_DIR, `section-${currentRule.section}-rule-${currentRule.subsection}.md`)
const ruleContent = currentRule.content.join('\n')
await writeFile(ruleFile, ruleContent, 'utf-8')
console.log(`Created ${ruleFile}`)
}
// Save last section
if (currentSection) {
const sectionFile = join(RULES_DIR, `section-${currentSection.number}.md`)
let sectionContent = `# ${currentSection.number}. ${currentSection.title}\n\n`
if (currentSection.impact) {
sectionContent += `**Impact: ${currentSection.impact}**\n\n`
}
if (currentSection.introduction) {
sectionContent += `## Introduction\n\n${currentSection.introduction}\n`
}
await writeFile(sectionFile, sectionContent, 'utf-8')
console.log(`Created ${sectionFile}`)
}
console.log('\n✓ Migration complete!')
console.log('Note: You may need to manually add frontmatter to rule files.')
} catch (error) {
console.error('Migration failed:', error)
process.exit(1)
}
}
migrate()
================================================
FILE: packages/react-best-practices-build/src/parser.ts
================================================
/**
* Parser for rule markdown files
*/
import { readFile } from 'fs/promises'
import { basename } from 'path'
import { Rule, ImpactLevel } from './types.js'
export interface RuleFile {
section: number
subsection?: number
rule: Rule
}
/**
* Parse a rule markdown file into a Rule object
*/
export async function parseRuleFile(
filePath: string,
sectionMap?: Record<string, number>
): Promise<RuleFile> {
const rawContent = await readFile(filePath, 'utf-8')
// Normalize Windows CRLF line endings to LF for consistent parsing
const content = rawContent.replace(/\r\n/g, '\n')
const lines = content.split('\n')
// Extract frontmatter if present
let frontmatter: Record<string, any> = {}
let contentStart = 0
if (content.startsWith('---')) {
const frontmatterEnd = content.indexOf('---', 3)
if (frontmatterEnd !== -1) {
const frontmatterText = content.slice(3, frontmatterEnd).trim()
frontmatterText.split('\n').forEach((line) => {
const [key, ...valueParts] = line.split(':')
if (key && valueParts.length) {
const value = valueParts.join(':').trim()
frontmatter[key.trim()] = value.replace(/^["']|["']$/g, '')
}
})
contentStart = frontmatterEnd + 3
}
}
// Parse the rule content
const ruleContent = content.slice(contentStart).trim()
const ruleLines = ruleContent.split('\n')
// Extract title (first # or ## heading)
let title = ''
let titleLine = 0
for (let i = 0; i < ruleLines.length; i++) {
if (ruleLines[i].startsWith('##')) {
title = ruleLines[i].replace(/^##+\s*/, '').trim()
titleLine = i
break
}
}
// Extract impact
let impact: Rule['impact'] = 'MEDIUM'
let impactDescription = ''
let explanation = ''
let examples: Rule['examples'] = []
let references: string[] = []
// Parse content after title
let currentExample: {
label: string
description?: string
code: string
language?: string
additionalText?: string
} | null = null
let inCodeBlock = false
let codeBlockLanguage = 'typescript'
let codeBlockContent: string[] = []
let afterCodeBlock = false
let additionalText: string[] = []
let hasCodeBlockForCurrentExample = false
for (let i = titleLine + 1; i < ruleLines.length; i++) {
const line = ruleLines[i]
// Impact line
if (line.includes('**Impact:')) {
const match = line.match(
/\*\*Impact:\s*(\w+(?:-\w+)?)\s*(?:\(([^)]+)\))?/i
)
if (match) {
impact = match[1].toUpperCase().replace(/-/g, '-') as ImpactLevel
impactDescription = match[2] || ''
}
continue
}
// Code block start
if (line.startsWith('```')) {
if (inCodeBlock) {
// End of code block
if (currentExample) {
currentExample.code = codeBlockContent.join('\n')
currentExample.language = codeBlockLanguage
}
codeBlockContent = []
inCodeBlock = false
afterCodeBlock = true
} else {
// Start of code block
inCodeBlock = true
hasCodeBlockForCurrentExample = true
codeBlockLanguage = line.slice(3).trim() || 'typescript'
codeBlockContent = []
afterCodeBlock = false
}
continue
}
if (inCodeBlock) {
codeBlockContent.push(line)
continue
}
// Example label (Incorrect, Correct, Example, Usage, Implementation, etc.)
// Match pattern: **Label:** or **Label (description):** at end of line
// This distinguishes example labels from inline bold text like "**Trade-off:** some text"
const labelMatch = line.match(/^\*\*([^:]+?):\*?\*?$/)
if (labelMatch) {
// Save previous example if it exists
if (currentExample) {
if (additionalText.length > 0) {
currentExample.additionalText = additionalText.join('\n\n')
additionalText = []
}
examples.push(currentExample)
}
afterCodeBlock = false
hasCodeBlockForCurrentExample = false
const fullLabel = labelMatch[1].trim()
// Try to extract description from parentheses if present (handles simple cases)
// For nested parentheses like "Incorrect (O(n) per lookup)", we keep the full label
const descMatch = fullLabel.match(
/^([A-Za-z]+(?:\s+[A-Za-z]+)*)\s*\(([^()]+)\)$/
)
currentExample = {
label: descMatch ? descMatch[1].trim() : fullLabel,
description: descMatch ? descMatch[2].trim() : undefined,
code: '',
language: codeBlockLanguage,
}
continue
}
// Reference links
if (line.startsWith('Reference:') || line.startsWith('References:')) {
// Save current example before processing references
if (currentExample) {
if (additionalText.length > 0) {
currentExample.additionalText = additionalText.join('\n\n')
additionalText = []
}
examples.push(currentExample)
currentExample = null
}
const refMatch = line.match(/\[([^\]]+)\]\(([^)]+)\)/g)
if (refMatch) {
references.push(
...refMatch.map((ref) => {
const m = ref.match(/\[([^\]]+)\]\(([^)]+)\)/)
return m ? m[2] : ref
})
)
}
continue
}
// Regular text (explanation or additional context after examples)
if (line.trim() && !line.startsWith('#')) {
if (!currentExample && !inCodeBlock) {
// Main explanation before any examples
explanation += (explanation ? '\n\n' : '') + line
} else if (
currentExample &&
(afterCodeBlock || !hasCodeBlockForCurrentExample)
) {
// Text after a code block, or text in a section without a code block
// (e.g., "When NOT to use this pattern:" with bullet points instead of code)
additionalText.push(line)
}
}
}
// Handle last example if still open
if (currentExample) {
if (additionalText.length > 0) {
currentExample.additionalText = additionalText.join('\n\n')
}
examples.push(currentExample)
}
// Infer section from filename patterns
// Pattern: area-description.md where area determines section
const filename = basename(filePath)
// Default section map (for backwards compatibility)
const defaultSectionMap: Record<string, number> = {
async: 1,
bundle: 2,
server: 3,
client: 4,
rerender: 5,
rendering: 6,
js: 7,
advanced: 8,
}
const effectiveSectionMap = sectionMap || defaultSectionMap
// Extract area from filename - try longest prefix match first
// This handles prefixes like "list-performance" vs "list"
const filenameParts = filename.replace('.md', '').split('-')
let section = 0
// Try progressively shorter prefixes to find the best match
for (let len = filenameParts.length; len > 0; len--) {
const prefix = filenameParts.slice(0, len).join('-')
if (effectiveSectionMap[prefix] !== undefined) {
section = effectiveSectionMap[prefix]
break
}
}
// Fall back to frontmatter section if specified
section = frontmatter.section || section || 0
const rule: Rule = {
id: '', // Will be assigned by build script based on sorted order
title: frontmatter.title || title,
section: section,
subsection: undefined,
impact: frontmatter.impact || impact,
impactDescription: frontmatter.impactDescription || impactDescription,
explanation: frontmatter.explanation || explanation.trim(),
examples,
references: frontmatter.references
? frontmatter.references.split(',').map((r: string) => r.trim())
: references,
tags: frontmatter.tags
? frontmatter.tags.split(',').map((t: string) => t.trim())
: undefined,
}
return {
section,
subsection: 0,
rule,
}
}
================================================
FILE: packages/react-best-practices-build/src/types.ts
================================================
/**
* Type definitions for React Performance Guidelines rules
*/
export type ImpactLevel = 'CRITICAL' | 'HIGH' | 'MEDIUM-HIGH' | 'MEDIUM' | 'LOW-MEDIUM' | 'LOW'
export interface CodeExample {
label: string // e.g., "Incorrect", "Correct", "Example"
description?: string // Optional description before code
code: string
language?: string // Default: 'typescript' or 'tsx'
additionalText?: string // Optional text after code block (explanations, reasons)
}
export interface Rule {
id: string // e.g., "1.1", "2.3"
title: string
section: number // Main section number (1-8)
subsection?: number // Subsection number within section
impact: ImpactLevel
impactDescription?: string // e.g., "2-10× improvement"
explanation: string
examples: CodeExample[]
references?: string[] // URLs or citations
tags?: string[] // For categorization/search
}
export interface Section {
number: number
title: string
impact: ImpactLevel
impactDescription?: string
introduction?: string
rules: Rule[]
}
export interface GuidelinesDocument {
version: string
organization: string
date: string
abstract: string
sections: Section[]
references?: string[]
}
export interface TestCase {
ruleId: string
ruleTitle: string
type: 'bad' | 'good'
code: string
language: string
description?: string
}
================================================
FILE: packages/react-best-practices-build/src/validate.ts
================================================
#!/usr/bin/env node
/**
* Validate rule files follow the correct structure
*/
import { readdir } from 'fs/promises'
import { join } from 'path'
import { Rule } from './types.js'
import { parseRuleFile } from './parser.js'
import { RULES_DIR } from './config.js'
interface ValidationError {
file: string
ruleId?: string
message: string
}
/**
* Validate a rule
*/
function validateRule(rule: Rule, file: string): ValidationError[] {
const errors: ValidationError[] = []
// Note: rule.id is auto-generated during build, not required in source files
if (!rule.title || rule.title.trim().length === 0) {
errors.push({ file, ruleId: rule.id, message: 'Missing or empty title' })
}
if (!rule.explanation || rule.explanation.trim().length === 0) {
errors.push({ file, ruleId: rule.id, message: 'Missing or empty explanation' })
}
if (!rule.examples || rule.examples.length === 0) {
errors.push({ file, ruleId: rule.id, message: 'Missing examples (need at least one bad and one good example)' })
} else {
// Filter out informational examples (notes, trade-offs, etc.) that don't have code
const codeExamples = rule.examples.filter(e => e.code && e.code.trim().length > 0)
const hasBad = codeExamples.some(e =>
e.label.toLowerCase().includes('incorrect') ||
e.label.toLowerCase().includes('wrong') ||
e.label.toLowerCase().includes('bad')
)
const hasGood = codeExamples.some(e =>
e.label.toLowerCase().includes('correct') ||
e.label.toLowerCase().includes('good') ||
e.label.toLowerCase().includes('usage') ||
e.label.toLowerCase().includes('implementation') ||
e.label.toLowerCase().includes('example')
)
if (codeExamples.length === 0) {
errors.push({ file, ruleId: rule.id, message: 'Missing code examples' })
} else if (!hasBad && !hasGood) {
errors.push({ file, ruleId: rule.id, message: 'Missing bad/incorrect or good/correct examples' })
}
}
const validImpacts: Rule['impact'][] = ['CRITICAL', 'HIGH', 'MEDIUM-HIGH', 'MEDIUM', 'LOW-MEDIUM', 'LOW']
if (!validImpacts.includes(rule.impact)) {
errors.push({ file, ruleId: rule.id, message: `Invalid impact level: ${rule.impact}. Must be one of: ${validImpacts.join(', ')}` })
}
return errors
}
/**
* Main validation function
*/
async function validate() {
try {
console.log('Validating rule files...')
console.log(`Rules directory: ${RULES_DIR}`)
const files = await readdir(RULES_DIR)
const ruleFiles = files.filter(f => f.endsWith('.md') && !f.startsWith('_'))
const allErrors: ValidationError[] = []
for (const file of ruleFiles) {
const filePath = join(RULES_DIR, file)
try {
const { rule } = await parseRuleFile(filePath)
const errors = validateRule(rule, file)
allErrors.push(...errors)
} catch (error) {
allErrors.push({
file,
message: `Failed to parse: ${error instanceof Error ? error.message : String(error)}`
})
}
}
if (allErrors.length > 0) {
console.error('\n✗ Validation failed:\n')
allErrors.forEach(error => {
console.error(` ${error.file}${error.ruleId ? ` (${error.ruleId})` : ''}: ${error.message}`)
})
process.exit(1)
} else {
console.log(`✓ All ${ruleFiles.length} rule files are valid`)
}
} catch (error) {
console.error('Validation failed:', error)
process.exit(1)
}
}
validate()
================================================
FILE: packages/react-best-practices-build/test-cases.json
================================================
[
{
"ruleId": "",
"ruleTitle": "Store Event Handlers in Refs",
"type": "bad",
"code": "function useWindowEvent(event: string, handler: (e) => void) {\n useEffect(() => {\n window.addEventListener(event, handler)\n return () => window.removeEventListener(event, handler)\n }, [event, handler])\n}",
"language": "tsx",
"description": "re-subscribes on every render"
},
{
"ruleId": "",
"ruleTitle": "Store Event Handlers in Refs",
"type": "good",
"code": "import { 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}",
"language": "tsx",
"description": "stable subscription"
},
{
"ruleId": "",
"ruleTitle": "Initialize App Once, Not Per Mount",
"type": "bad",
"code": "function Comp() {\n useEffect(() => {\n loadFromStorage()\n checkAuthToken()\n }, [])\n\n // ...\n}",
"language": "tsx",
"description": "runs twice in dev, re-runs on remount"
},
{
"ruleId": "",
"ruleTitle": "Initialize App Once, Not Per Mount",
"type": "good",
"code": "let didInit = false\n\nfunction Comp() {\n useEffect(() => {\n if (didInit) return\n didInit = true\n loadFromStorage()\n checkAuthToken()\n }, [])\n\n // ...\n}",
"language": "tsx",
"description": "once per app load"
},
{
"ruleId": "",
"ruleTitle": "useEffectEvent for Stable Callback Refs",
"type": "bad",
"code": "function 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}",
"language": "tsx",
"description": "effect re-runs on every callback change"
},
{
"ruleId": "",
"ruleTitle": "useEffectEvent for Stable Callback Refs",
"type": "good",
"code": "import { 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}",
"language": "tsx",
"description": "using React's useEffectEvent"
},
{
"ruleId": "",
"ruleTitle": "Prevent Waterfall Chains in API Routes",
"type": "bad",
"code": "export 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}",
"language": "typescript",
"description": "config waits for auth, data waits for both"
},
{
"ruleId": "",
"ruleTitle": "Prevent Waterfall Chains in API Routes",
"type": "good",
"code": "export 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}",
"language": "typescript",
"description": "auth and config start immediately"
},
{
"ruleId": "",
"ruleTitle": "Defer Await Until Needed",
"type": "bad",
"code": "async 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}",
"language": "typescript",
"description": "blocks both branches"
},
{
"ruleId": "",
"ruleTitle": "Defer Await Until Needed",
"type": "good",
"code": "async 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}",
"language": "typescript",
"description": "only blocks when needed"
},
{
"ruleId": "",
"ruleTitle": "Dependency-Based Parallelization",
"type": "bad",
"code": "const [user, config] = await Promise.all([\n fetchUser(),\n fetchConfig()\n])\nconst profile = await fetchProfile(user.id)",
"language": "typescript",
"description": "profile waits for config unnecessarily"
},
{
"ruleId": "",
"ruleTitle": "Dependency-Based Parallelization",
"type": "good",
"code": "import { 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})",
"language": "typescript",
"description": "config and profile run in parallel"
},
{
"ruleId": "",
"ruleTitle": "Promise.all() for Independent Operations",
"type": "bad",
"code": "const user = await fetchUser()\nconst posts = await fetchPosts()\nconst comments = await fetchComments()",
"language": "typescript",
"description": "sequential execution, 3 round trips"
},
{
"ruleId": "",
"ruleTitle": "Promise.all() for Independent Operations",
"type": "good",
"code": "const [user, posts, comments] = await Promise.all([\n fetchUser(),\n fetchPosts(),\n fetchComments()\n])",
"language": "typescript",
"description": "parallel execution, 1 round trip"
},
{
"ruleId": "",
"ruleTitle": "Strategic Suspense Boundaries",
"type": "bad",
"code": "async function Page() {\n const data = await fetchData() // Blocks entire page\n \n return (\n <div>\n <div>Sidebar</div>\n <div>Header</div>\n <div>\n <DataDisplay data={data} />\n </div>\n <div>Footer</div>\n </div>\n )\n}",
"language": "tsx",
"description": "wrapper blocked by data fetching"
},
{
"ruleId": "",
"ruleTitle": "Strategic Suspense Boundaries",
"type": "good",
"code": "function Page() {\n return (\n <div>\n <div>Sidebar</div>\n <div>Header</div>\n <div>\n <Suspense fallback={<Skeleton />}>\n <DataDisplay />\n </Suspense>\n </div>\n <div>Footer</div>\n </div>\n )\n}\n\nasync function DataDisplay() {\n const data = await fetchData() // Only blocks this component\n return <div>{data.content}</div>\n}",
"language": "tsx",
"description": "wrapper shows immediately, data streams in"
},
{
"ruleId": "",
"ruleTitle": "Avoid Barrel File Imports",
"type": "bad",
"code": "import { 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",
"language": "tsx",
"description": "imports entire library"
},
{
"ruleId": "",
"ruleTitle": "Avoid Barrel File Imports",
"type": "good",
"code": "import Check from 'lucide-react/dist/esm/icons/check'\nimport X from 'lucide-react/dist/esm/icons/x'\nimport Menu from 'lucide-react/dist/esm/icons/menu'\n// Loads only 3 modules (~2KB vs ~1MB)\n\nimport Button from '@mui/material/Button'\nimport TextField from '@mui/material/TextField'\n// Loads only what you use",
"language": "tsx",
"description": "imports only what you need"
},
{
"ruleId": "",
"ruleTitle": "Defer Non-Critical Third-Party Libraries",
"type": "bad",
"code": "import { Analytics } from '@vercel/analytics/react'\n\nexport default function RootLayout({ children }) {\n return (\n <html>\n <body>\n {children}\n <Analytics />\n </body>\n </html>\n )\n}",
"language": "tsx",
"description": "blocks initial bundle"
},
{
"ruleId": "",
"ruleTitle": "Defer Non-Critical Third-Party Libraries",
"type": "good",
"code": "import 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 <html>\n <body>\n {children}\n <Analytics />\n </body>\n </html>\n )\n}",
"language": "tsx",
"description": "loads after hydration"
},
{
"ruleId": "",
"ruleTitle": "Dynamic Imports for Heavy Components",
"type": "bad",
"code": "import { MonacoEditor } from './monaco-editor'\n\nfunction CodePanel({ code }: { code: string }) {\n return <MonacoEditor value={code} />\n}",
"language": "tsx",
"description": "Monaco bundles with main chunk ~300KB"
},
{
"ruleId": "",
"ruleTitle": "Dynamic Imports for Heavy Components",
"type": "good",
"code": "import 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 <MonacoEditor value={code} />\n}",
"language": "tsx",
"description": "Monaco loads on demand"
},
{
"ruleId": "",
"ruleTitle": "Deduplicate Global Event Listeners",
"type": "bad",
"code": "function 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}",
"language": "tsx",
"description": "N instances = N listeners"
},
{
"ruleId": "",
"ruleTitle": "Deduplicate Global Event Listeners",
"type": "good",
"code": "import useSWRSubscription from 'swr/subscription'\n\n// Module-level Map to track callbacks per key\nconst keyCallbacks = new Map<string, Set<() => 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}",
"language": "tsx",
"description": "N instances = 1 listener"
},
{
"ruleId": "",
"ruleTitle": "Version and Minimize localStorage Data",
"type": "bad",
"code": "// No version, stores everything, no error handling\nlocalStorage.setItem('userConfig', JSON.stringify(fullUserObject))\nconst data = localStorage.getItem('userConfig')",
"language": "typescript",
"description": "Incorrect example for Version and Minimize localStorage Data"
},
{
"ruleId": "",
"ruleTitle": "Version and Minimize localStorage Data",
"type": "good",
"code": "const 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}",
"language": "typescript",
"description": "Correct example for Version and Minimize localStorage Data"
},
{
"ruleId": "",
"ruleTitle": "Use Passive Event Listeners for Scrolling Performance",
"type": "bad",
"code": "useEffect(() => {\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}, [])",
"language": "typescript",
"description": "Incorrect example for Use Passive Event Listeners for Scrolling Performance"
},
{
"ruleId": "",
"ruleTitle": "Use Passive Event Listeners for Scrolling Performance",
"type": "good",
"code": "useEffect(() => {\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}, [])",
"language": "typescript",
"description": "Correct example for Use Passive Event Listeners for Scrolling Performance"
},
{
"ruleId": "",
"ruleTitle": "Use SWR for Automatic Deduplication",
"type": "bad",
"code": "function UserList() {\n const [users, setUsers] = useState([])\n useEffect(() => {\n fetch('/api/users')\n .then(r => r.json())\n .then(setUsers)\n }, [])\n}",
"language": "tsx",
"description": "no deduplication, each instance fetches"
},
{
"ruleId": "",
"ruleTitle": "Use SWR for Automatic Deduplication",
"type": "good",
"code": "import useSWR from 'swr'\n\nfunction UserList() {\n const { data: users } = useSWR('/api/users', fetcher)\n}",
"language": "tsx",
"description": "multiple instances share one request"
},
{
"ruleId": "",
"ruleTitle": "Avoid Layout Thrashing",
"type": "bad",
"code": "function 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}",
"language": "typescript",
"description": "interleaved reads and writes force reflows"
},
{
"ruleId": "",
"ruleTitle": "Avoid Layout Thrashing",
"type": "good",
"code": "function 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}",
"language": "typescript",
"description": "batch writes, then read once"
},
{
"ruleId": "",
"ruleTitle": "Avoid Layout Thrashing",
"type": "good",
"code": "function updateElementStyles(element: HTMLElement) {\n element.classList.add('highlighted-box')\n \n const { width, height } = element.getBoundingClientRect()\n}",
"language": "typescript",
"description": "batch reads, then writes"
},
{
"ruleId": "",
"ruleTitle": "Cache Repeated Function Calls",
"type": "bad",
"code": "function ProjectList({ projects }: { projects: Project[] }) {\n return (\n <div>\n {projects.map(project => {\n // slugify() called 100+ times for same project names\n const slug = slugify(project.name)\n \n return <ProjectCard key={project.id} slug={slug} />\n })}\n </div>\n )\n}",
"language": "typescript",
"description": "redundant computation"
},
{
"ruleId": "",
"ruleTitle": "Cache Repeated Function Calls",
"type": "good",
"code": "// Module-level cache\nconst slugifyCache = new Map<string, string>()\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 <div>\n {projects.map(project => {\n // Computed only once per unique project name\n const slug = cachedSlugify(project.name)\n \n return <ProjectCard key={project.id} slug={slug} />\n })}\n </div>\n )\n}",
"language": "typescript",
"description": "cached results"
},
{
"ruleId": "",
"ruleTitle": "Cache Property Access in Loops",
"type": "bad",
"code": "for (let i = 0; i < arr.length; i++) {\n process(obj.config.settings.value)\n}",
"language": "typescript",
"description": "3 lookups × N iterations"
},
{
"ruleId": "",
"ruleTitle": "Cache Property Access in Loops",
"type": "good",
"code": "const value = obj.config.settings.value\nconst len = arr.length\nfor (let i = 0; i < len; i++) {\n process(value)\n}",
"language": "typescript",
"description": "1 lookup total"
},
{
"ruleId": "",
"ruleTitle": "Cache Storage API Calls",
"type": "bad",
"code": "function getTheme() {\n return localStorage.getItem('theme') ?? 'light'\n}\n// Called 10 times = 10 storage reads",
"language": "typescript",
"description": "reads storage on every call"
},
{
"ruleId": "",
"ruleTitle": "Cache Storage API Calls",
"type": "good",
"code": "const storageCache = new Map<string, string | null>()\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}",
"language": "typescript",
"description": "Map cache"
},
{
"ruleId": "",
"ruleTitle": "Combine Multiple Array Iterations",
"type": "bad",
"code": "const admins = users.filter(u => u.isAdmin)\nconst testers = users.filter(u => u.isTester)\nconst inactive = users.filter(u => !u.isActive)",
"language": "typescript",
"description": "3 iterations"
},
{
"ruleId": "",
"ruleTitle": "Combine Multiple Array Iterations",
"type": "good",
"code": "const 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}",
"language": "typescript",
"description": "1 iteration"
},
{
"ruleId": "",
"ruleTitle": "Early Return from Functions",
"type": "bad",
"code": "function 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}",
"language": "typescript",
"description": "processes all items even after finding answer"
},
{
"ruleId": "",
"ruleTitle": "Early Return from Functions",
"type": "good",
"code": "function 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}",
"language": "typescript",
"description": "returns immediately on first error"
},
{
"ruleId": "",
"ruleTitle": "Use flatMap to Map and Filter in One Pass",
"type": "bad",
"code": "const userNames = users\n .map(user => user.isActive ? user.name : null)\n .filter(Boolean)",
"language": "typescript",
"description": "2 iterations, intermediate array"
},
{
"ruleId": "",
"ruleTitle": "Use flatMap to Map and Filter in One Pass",
"type": "good",
"code": "const userNames = users.flatMap(user =>\n user.isActive ? [user.name] : []\n)",
"language": "typescript",
"description": "1 iteration, no intermediate array"
},
{
"ruleId": "",
"ruleTitle": "Hoist RegExp Creation",
"type": "bad",
"code": "function Highlighter({ text, query }: Props) {\n const regex = new RegExp(`(${query})`, 'gi')\n const parts = text.split(regex)\n return <>{parts.map((part, i) => ...)}</>\n}",
"language": "tsx",
"description": "new RegExp every render"
},
{
"ruleId": "",
"ruleTitle": "Hoist RegExp Creation",
"type": "good",
"code": "const 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}",
"language": "tsx",
"description": "memoize or hoist"
},
{
"ruleId": "",
"ruleTitle": "Build Index Maps for Repeated Lookups",
"type": "bad",
"code": "function processOrders(orders: Order[], users: User[]) {\n return orders.map(order => ({\n ...order,\n user: users.find(u => u.id === order.userId)\n }))\n}",
"language": "typescript",
"description": "Incorrect (O(n) per lookup) example for Build Index Maps for Repeated Lookups"
},
{
"ruleId": "",
"ruleTitle": "Build Index Maps for Repeated Lookups",
"type": "good",
"code": "function 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}",
"language": "typescript",
"description": "Correct (O(1) per lookup) example for Build Index Maps for Repeated Lookups"
},
{
"ruleId": "",
"ruleTitle": "Early Length Check for Array Comparisons",
"type": "bad",
"code": "function hasChanges(current: string[], original: string[]) {\n // Always sorts and joins, even when lengths differ\n return current.sort().join() !== original.sort().join()\n}",
"language": "typescript",
"description": "always runs expensive comparison"
},
{
"ruleId": "",
"ruleTitle": "Early Length Check for Array Comparisons",
"type": "good",
"code": "function 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}",
"language": "typescript",
"description": "Correct (O(1) length check first) example for Early Length Check for Array Comparisons"
},
{
"ruleId": "",
"ruleTitle": "Use Loop for Min/Max Instead of Sort",
"type": "bad",
"code": "interface 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}",
"language": "typescript",
"description": "Incorrect (O(n log n) - sort to find latest) example for Use Loop for Min/Max Instead of Sort"
},
{
"ruleId": "",
"ruleTitle": "Use Loop for Min/Max Instead of Sort",
"type": "bad",
"code": "function 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}",
"language": "typescript",
"description": "Incorrect (O(n log n) - sort for oldest and newest) example for Use Loop for Min/Max Instead of Sort"
},
{
"ruleId": "",
"ruleTitle": "Use Loop for Min/Max Instead of Sort",
"type": "good",
"code": "function 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}",
"language": "typescript",
"description": "Correct (O(n) - single loop) example for Use Loop for Min/Max Instead of Sort"
},
{
"ruleId": "",
"ruleTitle": "Use Set/Map for O(1) Lookups",
"type": "bad",
"code": "const allowedIds = ['a', 'b', 'c', ...]\nitems.filter(item => allowedIds.includes(item.id))",
"language": "typescript",
"description": "Incorrect (O(n) per check) example for Use Set/Map for O(1) Lookups"
},
{
"ruleId": "",
"ruleTitle": "Use Set/Map for O(1) Lookups",
"type": "good",
"code": "const allowedIds = new Set(['a', 'b', 'c', ...])\nitems.filter(item => allowedIds.has(item.id))",
"language": "typescript",
"description": "Correct (O(1) per check) example for Use Set/Map for O(1) Lookups"
},
{
"ruleId": "",
"ruleTitle": "Use toSorted() Instead of sort() for Immutability",
"type": "bad",
"code": "function 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 <div>{sorted.map(renderUser)}</div>\n}",
"language": "typescript",
"description": "mutates original array"
},
{
"ruleId": "",
"ruleTitle": "Use toSorted() Instead of sort() for Immutability",
"type": "good",
"code": "function 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 <div>{sorted.map(renderUser)}</div>\n}",
"language": "typescript",
"description": "creates new array"
},
{
"ruleId": "",
"ruleTitle": "Animate SVG Wrapper Instead of SVG Element",
"type": "bad",
"code": "function LoadingSpinner() {\n return (\n <svg \n className=\"animate-spin\"\n width=\"24\" \n height=\"24\" \n viewBox=\"0 0 24 24\"\n >\n <circle cx=\"12\" cy=\"12\" r=\"10\" stroke=\"currentColor\" />\n </svg>\n )\n}",
"language": "tsx",
"description": "animating SVG directly - no hardware acceleration"
},
{
"ruleId": "",
"ruleTitle": "Animate SVG Wrapper Instead of SVG Element",
"type": "good",
"code": "function LoadingSpinner() {\n return (\n <div className=\"animate-spin\">\n <svg \n width=\"24\" \n height=\"24\" \n viewBox=\"0 0 24 24\"\n >\n <circle cx=\"12\" cy=\"12\" r=\"10\" stroke=\"currentColor\" />\n </svg>\n </div>\n )\n}",
"language": "tsx",
"description": "animating wrapper div - hardware accelerated"
},
{
"ruleId": "",
"ruleTitle": "Use Explicit Conditional Rendering",
"type": "bad",
"code": "function Badge({ count }: { count: number }) {\n return (\n <div>\n {count && <span className=\"badge\">{count}</span>}\n </div>\n )\n}\n\n// When count = 0, renders: <div>0</div>\n// When count = 5, renders: <div><span class=\"badge\">5</span></div>",
"language": "tsx",
"description": "renders \"0\" when count is 0"
},
{
"ruleId": "",
"ruleTitle": "Use Explicit Conditional Rendering",
"type": "good",
"code": "function Badge({ count }: { count: number }) {\n return (\n <div>\n {count > 0 ? <span className=\"badge\">{count}</span> : null}\n </div>\n )\n}\n\n// When count = 0, renders: <div></div>\n// When count = 5, renders: <div><span class=\"badge\">5</span></div>",
"language": "tsx",
"description": "renders nothing when count is 0"
},
{
"ruleId": "",
"ruleTitle": "Hoist Static JSX Elements",
"type": "bad",
"code": "function LoadingSkeleton() {\n return <div className=\"animate-pulse h-20 bg-gray-200\" />\n}\n\nfunction Container() {\n return (\n <div>\n {loading && <LoadingSkeleton />}\n </div>\n )\n}",
"language": "tsx",
"description": "recreates element every render"
},
{
"ruleId": "",
"ruleTitle": "Hoist Static JSX Elements",
"type": "good",
"code": "const loadingSkeleton = (\n <div className=\"animate-pulse h-20 bg-gray-200\" />\n)\n\nfunction Container() {\n return (\n <div>\n {loading && loadingSkeleton}\n </div>\n )\n}",
"language": "tsx",
"description": "reuses same element"
},
{
"ruleId": "",
"ruleTitle": "Prevent Hydration Mismatch Without Flickering",
"type": "bad",
"code": "function ThemeWrapper({ children }: { children: ReactNode }) {\n // localStorage is not available on server - throws error\n const theme = localStorage.getItem('theme') || 'light'\n \n return (\n <div className={theme}>\n {children}\n </div>\n )\n}",
"language": "tsx",
"description": "breaks SSR"
},
{
"ruleId": "",
"ruleTitle": "Prevent Hydration Mismatch Without Flickering",
"type": "bad",
"code": "function 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 <div className={theme}>\n {children}\n </div>\n )\n}",
"language": "tsx",
"description": "visual flickering"
},
{
"ruleId": "",
"ruleTitle": "Prevent Hydration Mismatch Without Flickering",
"type": "good",
"code": "function ThemeWrapper({ children }: { children: ReactNode }) {\n return (\n <>\n <div id=\"theme-wrapper\">\n {children}\n </div>\n <script\n dangerouslySetInnerHTML={{\n __html: `\n (function() {\n try {\n var theme = localStorage.getItem('theme') || 'light';\n var el = document.getElementById('theme-wrapper');\n if (el) el.className = theme;\n } catch (e) {}\n })();\n `,\n }}\n />\n </>\n )\n}",
"language": "tsx",
"description": "no flicker, no hydration mismatch"
},
{
"ruleId": "",
"ruleTitle": "Suppress Expected Hydration Mismatches",
"type": "bad",
"code": "function Timestamp() {\n return <span>{new Date().toLocaleString()}</span>\n}",
"language": "tsx",
"description": "known mismatch warnings"
},
{
"ruleId": "",
"ruleTitle": "Suppress Expected Hydration Mismatches",
"type": "good",
"code": "function Timestamp() {\n return (\n <span suppressHydrationWarning>\n {new Date().toLocaleString()}\n </span>\n )\n}",
"language": "tsx",
"description": "suppress expected mismatch only"
},
{
"ruleId": "",
"ruleTitle": "Use defer or async on Script Tags",
"type": "bad",
"code": "export default function Document() {\n return (\n <html>\n <head>\n <script src=\"https://example.com/analytics.js\" />\n <script src=\"/scripts/utils.js\" />\n </head>\n <body>{/* content */}</body>\n </html>\n )\n}",
"language": "tsx",
"description": "blocks rendering"
},
{
"ruleId": "",
"ruleTitle": "Use defer or async on Script Tags",
"type": "good",
"code": "import Script from 'next/script'\n\nexport default function Page() {\n return (\n <>\n <Script src=\"https://example.com/analytics.js\" strategy=\"afterInteractive\" />\n <Script src=\"/scripts/utils.js\" strategy=\"beforeInteractive\" />\n </>\n )\n}",
"language": "tsx",
"description": "non-blocking"
},
{
"ruleId": "",
"ruleTitle": "Optimize SVG Precision",
"type": "bad",
"code": "<path d=\"M 10.293847 20.847362 L 30.938472 40.192837\" />",
"language": "svg",
"description": "excessive precision"
},
{
"ruleId": "",
"ruleTitle": "Optimize SVG Precision",
"type": "good",
"code": "<path d=\"M 10.3 20.8 L 30.9 40.2\" />",
"language": "svg",
"description": "1 decimal place"
},
{
"ruleId": "",
"ruleTitle": "Use useTransition Over Manual Loading States",
"type": "bad",
"code": "function SearchResults() {\n const [query, setQuery] = useState('')\n const [results, setResults] = useState([])\n const [isLoading, setIsLoading] = useState(false)\n\n const handleSearch = async (value: string) => {\n setIsLoading(true)\n setQuery(value)\n const data = await fetchResults(value)\n setResults(data)\n setIsLoading(false)\n }\n\n return (\n <>\n <input onChange={(e) => handleSearch(e.target.value)} />\n {isLoading && <Spinner />}\n <ResultsList results={results} />\n </>\n )\n}",
"language": "tsx",
"description": "manual loading state"
},
{
"ruleId": "",
"ruleTitle": "Use useTransition Over Manual Loading States",
"type": "good",
"code": "import { useTransition, useState } from 'react'\n\nfunction SearchResults() {\n const [query, setQuery] = useState('')\n const [results, setResults] = useState([])\n const [isPending, startTransition] = useTransition()\n\n const handleSearch = (value: string) => {\n setQuery(value) // Update input immediately\n \n startTransition(async () => {\n // Fetch and update results\n const data = await fetchResults(value)\n setResults(data)\n })\n }\n\n return (\n <>\n <input onChange={(e) => handleSearch(e.target.value)} />\n {isPending && <Spinner />}\n <ResultsList results={results} />\n </>\n )\n}",
"language": "tsx",
"description": "useTransition with built-in pending state"
},
{
"ruleId": "",
"ruleTitle": "Defer State Reads to Usage Point",
"type": "bad",
"code": "function ShareButton({ chatId }: { chatId: string }) {\n const searchParams = useSearchParams()\n\n const handleShare = () => {\n const ref = searchParams.get('ref')\n shareChat(chatId, { ref })\n }\n\n return <button onClick={handleShare}>Share</button>\n}",
"language": "tsx",
"description": "subscribes to all searchParams changes"
},
{
"ruleId": "",
"ruleTitle": "Defer State Reads to Usage Point",
"type": "good",
"code": "function ShareButton({ chatId }: { chatId: string }) {\n const handleShare = () => {\n const params = new URLSearchParams(window.location.search)\n const ref = params.get('ref')\n shareChat(chatId, { ref })\n }\n\n return <button onClick={handleShare}>Share</button>\n}",
"language": "tsx",
"description": "reads on demand, no subscription"
},
{
"ruleId": "",
"ruleTitle": "Narrow Effect Dependencies",
"type": "bad",
"code": "useEffect(() => {\n console.log(user.id)\n}, [user])",
"language": "tsx",
"description": "re-runs on any user field change"
},
{
"ruleId": "",
"ruleTitle": "Narrow Effect Dependencies",
"type": "good",
"code": "useEffect(() => {\n console.log(user.id)\n}, [user.id])",
"language": "tsx",
"description": "re-runs only when id changes"
},
{
"ruleId": "",
"ruleTitle": "Calculate Derived State During Rendering",
"type": "bad",
"code": "function Form() {\n const [firstName, setFirstName] = useState('First')\n const [lastName, setLastName] = useState('Last')\n const [fullName, setFullName] = useState('')\n\n useEffect(() => {\n setFullName(firstName + ' ' + lastName)\n }, [firstName, lastName])\n\n return <p>{fullName}</p>\n}",
"language": "tsx",
"description": "redundant state and effect"
},
{
"ruleId": "",
"ruleTitle": "Calculate Derived State During Rendering",
"type": "good",
"code": "function Form() {\n const [firstName, setFirstName] = useState('First')\n const [lastName, setLastName] = useState('Last')\n const fullName = firstName + ' ' + lastName\n\n return <p>{fullName}</p>\n}",
"language": "tsx",
"description": "derive during render"
},
{
"ruleId": "",
"ruleTitle": "Subscribe to Derived State",
"type": "bad",
"code": "function Sidebar() {\n const width = useWindowWidth() // updates continuously\n const isMobile = width < 768\n return <nav className={isMobile ? 'mobile' : 'desktop'} />\n}",
"language": "tsx",
"description": "re-renders on every pixel change"
},
{
"ruleId": "",
"ruleTitle": "Subscribe to Derived State",
"type": "good",
"code": "function Sidebar() {\n const isMobile = useMediaQuery('(max-width: 767px)')\n return <nav className={isMobile ? 'mobile' : 'desktop'} />\n}",
"language": "tsx",
"description": "re-renders only when boolean changes"
},
{
"ruleId": "",
"ruleTitle": "Use Functional setState Updates",
"type": "bad",
"code": "function TodoList() {\n const [items, setItems] = useState(initialItems)\n \n // Callback must depend on items, recreated on every items change\n const addItems = useCallback((newItems: Item[]) => {\n setItems([...items, ...newItems])\n }, [items]) // ❌ items dependency causes recreations\n \n // Risk of stale closure if dependency is forgotten\n const removeItem = useCallback((id: string) => {\n setItems(items.filter(item => item.id !== id))\n }, []) // ❌ Missing items dependency - will use stale items!\n \n return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />\n}",
"language": "tsx",
"description": "requires state as dependency"
},
{
"ruleId": "",
"ruleTitle": "Use Functional setState Updates",
"type": "good",
"code": "function TodoList() {\n const [items, setItems] = useState(initialItems)\n \n // Stable callback, never recreated\n const addItems = useCallback((newItems: Item[]) => {\n setItems(curr => [...curr, ...newItems])\n }, []) // ✅ No dependencies needed\n \n // Always uses latest state, no stale closure risk\n const removeItem = useCallback((id: string) => {\n setItems(curr => curr.filter(item => item.id !== id))\n }, []) // ✅ Safe and stable\n \n return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />\n}",
"language": "tsx",
"description": "stable callbacks, no stale closures"
},
{
"ruleId": "",
"ruleTitle": "Use Lazy State Initialization",
"type": "bad",
"code": "function FilteredList({ items }: { items: Item[] }) {\n // buildSearchIndex() runs on EVERY render, even after initialization\n const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))\n const [query, setQuery] = useState('')\n \n // When query changes, buildSearchIndex runs again unnecessarily\n return <SearchResults index={searchIndex} query={query} />\n}\n\nfunction UserProfile() {\n // JSON.parse runs on every render\n const [settings, setSettings] = useState(\n JSON.parse(localStorage.getItem('settings') || '{}')\n )\n \n return <SettingsForm settings={settings} onChange={setSettings} />\n}",
"language": "tsx",
"description": "runs on every render"
},
{
"ruleId": "",
"ruleTitle": "Use Lazy State Initialization",
"type": "good",
"code": "function FilteredList({ items }: { items: Item[] }) {\n // buildSearchIndex() runs ONLY on initial render\n const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))\n const [query, setQuery] = useState('')\n \n return <SearchResults index={searchIndex} query={query} />\n}\n\nfunction UserProfile() {\n // JSON.parse runs only on initial render\n const [settings, setSettings] = useState(() => {\n const stored = localStorage.getItem('settings')\n return stored ? JSON.parse(stored) : {}\n })\n \n return <SettingsForm settings={settings} onChange={setSettings} />\n}",
"language": "tsx",
"description": "runs only once"
},
{
"ruleId": "",
"ruleTitle": "Extract Default Non-primitive Parameter Value from Memoized Component to Constant",
"type": "bad",
"code": "const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {\n // ...\n})\n\n// Used without optional onClick\n<UserAvatar />",
"language": "tsx",
"description": "`onClick` has different values on every rerender"
},
{
"ruleId": "",
"ruleTitle": "Extract Default Non-primitive Parameter Value from Memoized Component to Constant",
"type": "good",
"code": "const NOOP = () => {};\n\nconst UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {\n // ...\n})\n\n// Used without optional onClick\n<UserAvatar />",
"language": "tsx",
"description": "stable default value"
},
{
"ruleId": "",
"ruleTitle": "Extract to Memoized Components",
"type": "bad",
"code": "function Profile({ user, loading }: Props) {\n const avatar = useMemo(() => {\n const id = computeAvatarId(user)\n return <Avatar id={id} />\n }, [user])\n\n if (loading) return <Skeleton />\n return <div>{avatar}</div>\n}",
"language": "tsx",
"description": "computes avatar even when loading"
},
{
"ruleId": "",
"ruleTitle": "Extract to Memoized Components",
"type": "good",
"code": "const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {\n const id = useMemo(() => computeAvatarId(user), [user])\n return <Avatar id={id} />\n})\n\nfunction Profile({ user, loading }: Props) {\n if (loading) return <Skeleton />\n return (\n <div>\n <UserAvatar user={user} />\n </div>\n )\n}",
"language": "tsx",
"description": "skips computation when loading"
},
{
"ruleId": "",
"ruleTitle": "Put Interaction Logic in Event Handlers",
"type": "bad",
"code": "function Form() {\n const [submitted, setSubmitted] = useState(false)\n const theme = useContext(ThemeContext)\n\n useEffect(() => {\n if (submitted) {\n post('/api/register')\n showToast('Registered', theme)\n }\n }, [submitted, theme])\n\n return <button onClick={() => setSubmitted(true)}>Submit</button>\n}",
"language": "tsx",
"description": "event modeled as state + effect"
},
{
"ruleId": "",
"ruleTitle": "Put Interaction Logic in Event Handlers",
"type": "good",
"code": "function Form() {\n const theme = useContext(ThemeContext)\n\n function handleSubmit() {\n post('/api/register')\n showToast('Registered', theme)\n }\n\n return <button onClick={handleSubmit}>Submit</button>\n}",
"language": "tsx",
"description": "do it in the handler"
},
{
"ruleId": "",
"ruleTitle": "Don't Define Components Inside Components",
"type": "bad",
"code": "function UserProfile({ user, theme }) {\n // Defined inside to access `theme` - BAD\n const Avatar = () => (\n <img\n src={user.avatarUrl}\n className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}\n />\n )\n\n // Defined inside to access `user` - BAD\n const Stats = () => (\n <div>\n <span>{user.followers} followers</span>\n <span>{user.posts} posts</span>\n </div>\n )\n\n return (\n <div>\n <Avatar />\n <Stats />\n </div>\n )\n}",
"language": "tsx",
"description": "remounts on every render"
},
{
"ruleId": "",
"ruleTitle": "Don't Define Components Inside Components",
"type": "good",
"code": "function Avatar({ src, theme }: { src: string; theme: string }) {\n return (\n <img\n src={src}\n className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}\n />\n )\n}\n\nfunction Stats({ followers, posts }: { followers: number; posts: number }) {\n return (\n <div>\n <span>{followers} followers</span>\n <span>{posts} posts</span>\n </div>\n )\n}\n\nfunction UserProfile({ user, theme }) {\n return (\n <div>\n <Avatar src={user.avatarUrl} theme={theme} />\n <Stats followers={user.followers} posts={user.posts} />\n </div>\n )\n}",
"language": "tsx",
"description": "pass props instead"
},
{
"ruleId": "",
"ruleTitle": "Do not wrap a simple expression with a primitive result type in useMemo",
"type": "bad",
"code": "function Header({ user, notifications }: Props) {\n const isLoading = useMemo(() => {\n return user.isLoading || notifications.isLoading\n }, [user.isLoading, notifications.isLoading])\n\n if (isLoading) return <Skeleton />\n // return some markup\n}",
"language": "tsx",
"description": "Incorrect example for Do not wrap a simple expression with a primitive result type in useMemo"
},
{
"ruleId": "",
"ruleTitle": "Do not wrap a simple expression with a primitive result type in useMemo",
"type": "good",
"code": "function Header({ user, notifications }: Props) {\n const isLoading = user.isLoading || notifications.isLoading\n\n if (isLoading) return <Skeleton />\n // return some markup\n}",
"language": "tsx",
"description": "Correct example for Do not wrap a simple expression with a primitive result type in useMemo"
},
{
"ruleId": "",
"ruleTitle": "Split Combined Hook Computations",
"type": "bad",
"code": "const sortedProducts = useMemo(() => {\n const filtered = products.filter((p) => p.category === category)\n const sorted = filtered.toSorted((a, b) =>\n sortOrder === \"asc\" ? a.price - b.price : b.price - a.price\n )\n return sorted\n}, [products, category, sortOrder])",
"language": "tsx",
"description": "changing `sortOrder` recomputes filtering"
},
{
"ruleId": "",
"ruleTitle": "Split Combined Hook Computations",
"type": "good",
"code": "const filteredProducts = useMemo(\n () => products.filter((p) => p.category === category),\n [products, category]\n)\n\nconst sortedProducts = useMemo(\n () =>\n filteredProducts.toSorted((a, b) =>\n sortOrder === \"asc\" ? a.price - b.price : b.price - a.price\n ),\n [filteredProducts, sortOrder]\n)",
"language": "tsx",
"description": "filtering only recomputes when products or category change"
},
{
"ruleId": "",
"ruleTitle": "Split Combined Hook Computations",
"type": "bad",
"code": "useEffect(() => {\n analytics.trackPageView(pathname)\n document.title = `${pageTitle} | My App`\n}, [pathname, pageTitle])",
"language": "tsx",
"description": "both effects run when either dependency changes"
},
{
"ruleId": "",
"ruleTitle": "Split Combined Hook Computations",
"type": "good",
"code": "useEffect(() => {\n analytics.trackPageView(pathname)\n}, [pathname])\n\nuseEffect(() => {\n document.title = `${pageTitle} | My App`\n}, [pageTitle])",
"language": "tsx",
"description": "effects run independently"
},
{
"ruleId": "",
"ruleTitle": "Use Transitions for Non-Urgent Updates",
"type": "bad",
"code": "function ScrollTracker() {\n const [scrollY, setScrollY] = useState(0)\n useEffect(() => {\n const handler = () => setScrollY(window.scrollY)\n window.addEventListener('scroll', handler, { passive: true })\n return () => window.removeEventListener('scroll', handler)\n }, [])\n}",
"language": "tsx",
"description": "blocks UI on every scroll"
},
{
"ruleId": "",
"ruleTitle": "Use Transitions for Non-Urgent Updates",
"type": "good",
"code": "import { startTransition } from 'react'\n\nfunction ScrollTracker() {\n const [scrollY, setScrollY] = useState(0)\n useEffect(() => {\n const handler = () => {\n startTransition(() => setScrollY(window.scrollY))\n }\n window.addEventListener('scroll', handler, { passive: true })\n return () => window.removeEventListener('scroll', handler)\n }, [])\n}",
"language": "tsx",
"description": "non-blocking updates"
},
{
"ruleId": "",
"ruleTitle": "Use useDeferredValue for Expensive Derived Renders",
"type": "bad",
"code": "function Search({ items }: { items: Item[] }) {\n const [query, setQuery] = useState('')\n const filtered = items.filter(item => fuzzyMatch(item, query))\n\n return (\n <>\n <input value={query} onChange={e => setQuery(e.target.value)} />\n <ResultsList results={filtered} />\n </>\n )\n}",
"language": "tsx",
"description": "input feels laggy while filtering"
},
{
"ruleId": "",
"ruleTitle": "Use useDeferredValue for Expensive Derived Renders",
"type": "good",
"code": "function Search({ items }: { items: Item[] }) {\n const [query, setQuery] = useState('')\n const deferredQuery = useDeferredValue(query)\n const filtered = useMemo(\n () => items.filter(item => fuzzyMatch(item, deferredQuery)),\n [items, deferredQuery]\n )\n const isStale = query !== deferredQuery\n\n return (\n <>\n <input value={query} onChange={e => setQuery(e.target.value)} />\n <div style={{ opacity: isStale ? 0.7 : 1 }}>\n <ResultsList results={filtered} />\n </div>\n </>\n )\n}",
"language": "tsx",
"description": "input stays snappy, results render when ready"
},
{
"ruleId": "",
"ruleTitle": "Use useRef for Transient Values",
"type": "bad",
"code": "function Tracker() {\n const [lastX, setLastX] = useState(0)\n\n useEffect(() => {\n const onMove = (e: MouseEvent) => setLastX(e.clientX)\n window.addEventListener('mousemove', onMove)\n return () => window.removeEventListener('mousemove', onMove)\n }, [])\n\n return (\n <div\n style={{\n position: 'fixed',\n top: 0,\n left: lastX,\n width: 8,\n height: 8,\n background: 'black',\n }}\n />\n )\n}",
"language": "tsx",
"description": "renders every update"
},
{
"ruleId": "",
"ruleTitle": "Use useRef for Transient Values",
"type": "good",
"code": "function Tracker() {\n const lastXRef = useRef(0)\n const dotRef = useRef<HTMLDivElement>(null)\n\n useEffect(() => {\n const onMove = (e: MouseEvent) => {\n lastXRef.current = e.clientX\n const node = dotRef.current\n if (node) {\n node.style.transform = `translateX(${e.clientX}px)`\n }\n }\n window.addEventListener('mousemove', onMove)\n return () => window.removeEventListener('mousemove', onMove)\n }, [])\n\n return (\n <div\n ref={dotRef}\n style={{\n position: 'fixed',\n top: 0,\n left: 0,\n width: 8,\n height: 8,\n background: 'black',\n transform: 'translateX(0px)',\n }}\n />\n )\n}",
"language": "tsx",
"description": "no re-render for tracking"
},
{
"ruleId": "",
"ruleTitle": "Use after() for Non-Blocking Operations",
"type": "bad",
"code": "import { logUserAction } from '@/app/utils'\n\nexport async function POST(request: Request) {\n // Perform mutation\n await updateDatabase(request)\n \n // Logging blocks the response\n const userAgent = request.headers.get('user-agent') || 'unknown'\n await logUserAction({ userAgent })\n \n return new Response(JSON.stringify({ status: 'success' }), {\n status: 200,\n headers: { 'Content-Type': 'application/json' }\n })\n}",
"language": "tsx",
"description": "blocks response"
},
{
"ruleId": "",
"ruleTitle": "Use after() for Non-Blocking Operations",
"type": "good",
"code": "import { after } from 'next/server'\nimport { headers, cookies } from 'next/headers'\nimport { logUserAction } from '@/app/utils'\n\nexport async function POST(request: Request) {\n // Perform mutation\n await updateDatabase(request)\n \n // Log after response is sent\n after(async () => {\n const userAgent = (await headers()).get('user-agent') || 'unknown'\n const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'\n \n logUserAction({ sessionCookie, userAgent })\n })\n \n return new Response(JSON.stringify({ status: 'success' }), {\n status: 200,\n headers: { 'Content-Type': 'application/json' }\n })\n}",
"language": "tsx",
"description": "non-blocking"
},
{
"ruleId": "",
"ruleTitle": "Authenticate Server Actions Like API Routes",
"type": "bad",
"code": "'use server'\n\nexport async function deleteUser(userId: string) {\n // Anyone can call this! No auth check\n await db.user.delete({ where: { id: userId } })\n return { success: true }\n}",
"language": "typescript",
"description": "no authentication check"
},
{
"ruleId": "",
"ruleTitle": "Authenticate Server Actions Like API Routes",
"type": "good",
"code": "'use server'\n\nimport { verifySession } from '@/lib/auth'\nimport { unauthorized } from '@/lib/errors'\n\nexport async function deleteUser(userId: string) {\n // Always check auth inside the action\n const session = await verifySession()\n \n if (!session) {\n throw unauthorized('Must be logged in')\n }\n \n // Check authorization too\n if (session.user.role !== 'admin' && session.user.id !== userId) {\n throw unauthorized('Cannot delete other users')\n }\n \n await db.user.delete({ where: { id: userId } })\n return { success: true }\n}",
"language": "typescript",
"description": "authentication inside the action"
},
{
"ruleId": "",
"ruleTitle": "Per-Request Deduplication with React.cache()",
"type": "bad",
"code": "const getUser = cache(async (params: { uid: number }) => {\n return await db.user.findUnique({ where: { id: params.uid } })\n})\n\n// Each call creates new object, never hits cache\ngetUser({ uid: 1 })\ngetUser({ uid: 1 }) // Cache miss, runs query again",
"language": "typescript",
"description": "always cache miss"
},
{
"ruleId": "",
"ruleTitle": "Per-Request Deduplication with React.cache()",
"type": "good",
"code": "const params = { uid: 1 }\ngetUser(params) // Query runs\ngetUser(params) // Cache hit (same reference)",
"language": "typescript",
"description": "cache hit"
},
{
"ruleId": "",
"ruleTitle": "Avoid Duplicate Serialization in RSC Props",
"type": "bad",
"code": "// RSC: sends 6 strings (2 arrays × 3 items)\n<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />",
"language": "tsx",
"description": "duplicates array"
},
{
"ruleId": "",
"ruleTitle": "Avoid Duplicate Serialization in RSC Props",
"type": "good",
"code": "// RSC: send once\n<ClientList usernames={usernames} />\n\n// Client: transform there\n'use client'\nconst sorted = useMemo(() => [...usernames].sort(), [usernames])",
"language": "tsx",
"description": "sends 3 strings"
},
{
"ruleId": "",
"ruleTitle": "Parallel Data Fetching with Component Composition",
"type": "bad",
"code": "export default async function Page() {\n const header = await fetchHeader()\n return (\n <div>\n <div>{header}</div>\n <Sidebar />\n </div>\n )\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return <nav>{items.map(renderItem)}</nav>\n}",
"language": "tsx",
"description": "Sidebar waits for Page's fetch to complete"
},
{
"ruleId": "",
"ruleTitle": "Parallel Data Fetching with Component Composition",
"type": "good",
"code": "async function Header() {\n const data = await fetchHeader()\n return <div>{data}</div>\n}\n\nasync function Sidebar() {\n const items = await fetchSidebarItems()\n return <nav>{items.map(renderItem)}</nav>\n}\n\nexport default function Page() {\n return (\n <div>\n <Header />\n <Sidebar />\n </div>\n )\n}",
"language": "tsx",
"description": "both fetch simultaneously"
},
{
"ruleId": "",
"ruleTitle": "Minimize Serialization at RSC Boundaries",
"type": "bad",
"code": "async function Page() {\n const user = await fetchUser() // 50 fields\n return <Profile user={user} />\n}\n\n'use client'\nfunction Profile({ user }: { user: User }) {\n return <div>{user.name}</div> // uses 1 field\n}",
"language": "tsx",
"description": "serializes all 50 fields"
},
{
"ruleId": "",
"ruleTitle": "Minimize Serialization at RSC Boundaries",
"type": "good",
"code": "async function Page() {\n const user = await fetchUser()\n return <Profile name={user.name} />\n}\n\n'use client'\nfunction Profile({ name }: { name: string }) {\n return <div>{name}</div>\n}",
"language": "tsx",
"description": "serializes only 1 field"
}
]
================================================
FILE: packages/react-best-practices-build/tsconfig.json
================================================
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"lib": ["ES2022"],
"moduleResolution": "node",
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
================================================
FILE: skills/composition-patterns/AGENTS.md
================================================
# React Composition Patterns
**Version 1.0.0**
Engineering
January 2026
> **Note:**
> This document is mainly for agents and LLMs to follow when maintaining,
> generating, or refactoring React codebases using composition. Humans
> may also find it useful, but guidance here is optimized for automation
> and consistency by AI-assisted workflows.
---
## Abstract
Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.
---
## Table of Contents
1. [Component Architecture](#1-component-architecture) — **HIGH**
- 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)
- 1.2 [Use Compound Components](#12-use-compound-components)
2. [State Management](#2-state-management) — **MEDIUM**
- 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)
- 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)
- 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)
3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**
- 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)
- 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)
4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**
- 4.1 [React 19 API Changes](#41-react-19-api-changes)
---
## 1. Component Architecture
**Impact: HIGH**
Fundamental patterns for structuring components to avoid prop
proliferation and enable flexible composition.
### 1.1 Avoid Boolean Prop Proliferation
**Impact: CRITICAL (prevents unmaintainable component variants)**
Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
component behavior. Each boolean doubles possible states and creates
unmaintainable conditional logic. Use composition instead.
**Incorrect: boolean props create exponential complexity**
```tsx
function Composer({
onSubmit,
isThread,
channelId,
isDMThread,
dmId,
isEditing,
isForwarding,
}: Props) {
return (
<form>
<Header />
<Input />
{isDMThread ? (
<AlsoSendToDMField id={dmId} />
) : isThread ? (
<AlsoSendToChannelField id={channelId} />
) : null}
{isEditing ? (
<EditActions />
) : isForwarding ? (
<ForwardActions />
) : (
<DefaultActions />
)}
<Footer onSubmit={onSubmit} />
</form>
)
}
```
**Correct: composition eliminates conditionals**
```tsx
// Channel composer
function ChannelComposer() {
return (
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<Composer.Footer>
<Composer.Attachments />
<Composer.Formatting />
<Composer.Emojis />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
)
}
// Thread composer - adds "also send to channel" field
function ThreadComposer({ channelId }: { channelId: string }) {
return (
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<AlsoSendToChannelField id={channelId} />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
)
}
// Edit composer - different footer actions
function EditComposer() {
return (
<Composer.Frame>
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.CancelEdit />
<Composer.SaveEdit />
</Composer.Footer>
</Composer.Frame>
)
}
```
Each variant is explicit about what it renders. We can share internals without
sharing a single monolithic parent.
### 1.2 Use Compound Components
**Impact: HIGH (enables flexible composition without prop drilling)**
Structure complex components as compound components with a shared context. Each
subcomponent accesses shared state via context, not props. Consumers compose the
pieces they need.
**Incorrect: monolithic component with render props**
```tsx
function Composer({
renderHeader,
renderFooter,
renderActions,
showAttachments,
showFormatting,
showEmojis,
}: Props) {
return (
<form>
{renderHeader?.()}
<Input />
{showAttachments && <Attachments />}
{renderFooter ? (
renderFooter()
) : (
<Footer>
{showFormatting && <Formatting />}
{showEmojis && <Emojis />}
{renderActions?.()}
</Footer>
)}
</form>
)
}
```
**Correct: compound components with shared context**
```tsx
const ComposerContext = createContext<ComposerContextValue | null>(null)
function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
return (
<ComposerContext value={{ state, actions, meta }}>
{children}
</ComposerContext>
)
}
function ComposerFrame({ children }: { children: React.ReactNode }) {
return <form>{children}</form>
}
function ComposerInput() {
const {
state,
actions: { update },
meta: { inputRef },
} = use(ComposerContext)
return (
<TextInput
ref={inputRef}
value={state.input}
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
/>
)
}
function ComposerSubmit() {
const {
actions: { submit },
} = use(ComposerContext)
return <Button onPress={submit}>Send</Button>
}
// Export as compound component
const Composer = {
Provider: ComposerProvider,
Frame: ComposerFrame,
Input: ComposerInput,
Submit: ComposerSubmit,
Header: ComposerHeader,
Footer: ComposerFooter,
Attachments: ComposerAttachments,
Formatting: ComposerFormatting,
Emojis: ComposerEmojis,
}
```
**Usage:**
```tsx
<Composer.Provider state={state} actions={actions} meta={meta}>
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
</Composer.Provider>
```
Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
---
## 2. State Management
**Impact: MEDIUM**
Patterns for lifting state and managing shared context across
composed components.
### 2.1 Decouple State Management from UI
**Impact: MEDIUM (enables swapping state implementations without changing UI)**
The provider component should be the only place that knows how state is managed.
UI components consume the context interface—they don't know if state comes from
useState, Zustand, or a server sync.
**Incorrect: UI coupled to state implementation**
```tsx
function ChannelComposer({ channelId }: { channelId: string }) {
// UI component knows about global state implementation
const state = useGlobalChannelState(channelId)
const { submit, updateInput } = useChannelSync(channelId)
return (
<Composer.Frame>
<Composer.Input
value={state.input}
onChange={(text) => sync.updateInput(text)}
/>
<Composer.Submit onPress={() => sync.submit()} />
</Composer.Frame>
)
}
```
**Correct: state management isolated in provider**
```tsx
// Provider handles all state management details
function ChannelProvider({
channelId,
children,
}: {
channelId: string
children: React.ReactNode
}) {
const { state, update, submit } = useGlobalChannel(channelId)
const inputRef = useRef(null)
return (
<Composer.Provider
state={state}
actions={{ update, submit }}
meta={{ inputRef }}
>
{children}
</Composer.Provider>
)
}
// UI component only knows about the context interface
function ChannelComposer() {
return (
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<Composer.Footer>
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
)
}
// Usage
function Channel({ channelId }: { channelId: string }) {
return (
<ChannelProvider channelId={channelId}>
<ChannelComposer />
</ChannelProvider>
)
}
```
**Different providers, same UI:**
```tsx
// Local state for ephemeral forms
function ForwardMessageProvider({ children }) {
const [state, setState] = useState(initialState)
const forwardMessage = useForwardMessage()
return (
<Composer.Provider
state={state}
actions={{ update: setState, submit: forwardMessage }}
>
{children}
</Composer.Provider>
)
}
// Global synced state for channels
function ChannelProvider({ channelId, children }) {
const { state, update, submit } = useGlobalChannel(channelId)
return (
<Composer.Provider state={state} actions={{ update, submit }}>
{children}
</Composer.Provider>
)
}
```
The same `Composer.Input` component works with both providers because it only
depends on the context interface, not the implementation.
### 2.2 Define Generic Context Interfaces for Dependency Injection
**Impact: HIGH (enables dependency-injectable state across use-cases)**
Define a **generic interface** for your component context with three parts:
`state`, `actions`, and `meta`. This interface is a contract that any provider
can implement—enabling the same UI components to work with completely different
state implementations.
**Core principle:** Lift state, compose internals, make state
dependency-injectable.
**Incorrect: UI coupled to specific state implementation**
```tsx
function ComposerInput() {
// Tightly coupled to a specific hook
const { input, setInput } = useChannelComposerState()
return <TextInput value={input} onChangeText={setInput} />
}
```
**Correct: generic interface enables dependency injection**
```tsx
// Define a GENERIC interface that any provider can implement
interface ComposerState {
input: string
attachments: Attachment[]
isSubmitting: boolean
}
interface ComposerActions {
update: (updater: (state: ComposerState) => ComposerState) => void
submit: () => void
}
interface ComposerMeta {
inputRef: React.RefObject<TextInput>
}
interface ComposerContextValue {
state: ComposerState
actions: ComposerActions
meta: ComposerMeta
}
const ComposerContext = createContext<ComposerContextValue | null>(null)
```
**UI components consume the interface, not the implementation:**
```tsx
function ComposerInput() {
const {
state,
actions: { update },
meta,
} = use(ComposerContext)
// This component works with ANY provider that implements the interface
return (
<TextInput
ref={meta.inputRef}
value={state.input}
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
/>
)
}
```
**Different providers implement the same interface:**
```tsx
// Provider A: Local state for ephemeral forms
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
const [state, setState] = useState(initialState)
const inputRef = useRef(null)
const submit = useForwardMessage()
return (
<ComposerContext
value={{
state,
actions: { update: setState, submit },
meta: { inputRef },
}}
>
{children}
</ComposerContext>
)
}
// Provider B: Global synced state for channels
function ChannelProvider({ channelId, children }: Props) {
const { state, update, submit } = useGlobalChannel(channelId)
const inputRef = useRef(null)
return (
<ComposerContext
value={{
state,
actions: { update, submit },
meta: { inputRef },
}}
>
{children}
</ComposerContext>
)
}
```
**The same composed UI works with both:**
```tsx
// Works with ForwardMessageProvider (local state)
<ForwardMessageProvider>
<Composer.Frame>
<Composer.Input />
<Composer.Submit />
</Composer.Frame>
</ForwardMessageProvider>
// Works with ChannelProvider (global synced state)
<ChannelProvider channelId="abc">
<Composer.Frame>
<Composer.Input />
<Composer.Submit />
</Composer.Frame>
</ChannelProvider>
```
**Custom UI outside the component can access state and actions:**
```tsx
function ForwardMessageDialog() {
return (
<ForwardMessageProvider>
<Dialog>
{/* The composer UI */}
<Composer.Frame>
<Composer.Input placeholder="Add a message, if you'd like." />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
</Composer.Footer>
</Composer.Frame>
{/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
<MessagePreview />
{/* Actions at the bottom of the dialog */}
<DialogActions>
<CancelButton />
<ForwardButton />
</DialogActions>
</Dialog>
</ForwardMessageProvider>
)
}
// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
function ForwardButton() {
const {
actions: { submit },
} = use(ComposerContext)
return <Button onPress={submit}>Forward</Button>
}
// This preview lives OUTSIDE Composer.Frame but can read composer's state!
function MessagePreview() {
const { state } = use(ComposerContext)
return <Preview message={state.input} attachments={state.attachments} />
}
```
The provider boundary is what matters—not the visual nesting. Components that
need shared state don't have to be inside the `Composer.Frame`. They just need
to be within the provider.
The `ForwardButton` and `MessagePreview` are not visually inside the composer
box, but they can still access its state and actions. This is the power of
lifting state into providers.
The UI is reusable bits you compose together. The state is dependency-injected
by the provider. Swap the provider, keep the UI.
### 2.3 Lift State into Provider Components
**Impact: HIGH (enables state sharing outside component boundaries)**
Move state management into dedicated provider components. This allows sibling
components outside the main UI to access and modify state without prop drilling
or awkward refs.
**Incorrect: state trapped inside component**
```tsx
function ForwardMessageComposer() {
const [state, setState] = useState(initialState)
const forwardMessage = useForwardMessage()
return (
<Composer.Frame>
<Composer.Input />
<Composer.Footer />
</Composer.Frame>
)
}
// Problem: How does this button access composer state?
function ForwardMessageDialog() {
return (
<Dialog>
<ForwardMessageComposer />
<MessagePreview /> {/* Needs composer state */}
<DialogActions>
<CancelButton />
<ForwardButton /> {/* Needs to call submit */}
</DialogActions>
</Dialog>
)
}
```
**Incorrect: useEffect to sync state up**
```tsx
function ForwardMessageDialog() {
const [input, setInput] = useState('')
return (
<Dialog>
<ForwardMessageComposer onInputChange={setInput} />
<MessagePreview input={input} />
</Dialog>
)
}
function ForwardMessageComposer({ onInputChange }) {
const [state, setState] = useState(initialState)
useEffect(() => {
onInputChange(state.input) // Sync on every change 😬
}, [state.input])
}
```
**Incorrect: reading state from ref on submit**
```tsx
function ForwardMessageDialog() {
const stateRef = useRef(null)
return (
<Dialog>
<ForwardMessageComposer stateRef={stateRef} />
<ForwardButton onPress={() => submit(stateRef.current)} />
</Dialog>
)
}
```
**Correct: state lifted to provider**
```tsx
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
const [state, setState] = useState(initialState)
const forwardMessage = useForwardMessage()
const inputRef = useRef(null)
return (
<Composer.Provider
state={state}
actions={{ update: setState, submit: forwardMessage }}
meta={{ inputRef }}
>
{children}
</Composer.Provider>
)
}
function ForwardMessageDialog() {
return (
<ForwardMessageProvider>
<Dialog>
<ForwardMessageComposer />
<MessagePreview /> {/* Custom components can access state and actions */}
<DialogActions>
<CancelButton />
<ForwardButton /> {/* Custom components can access state and actions */}
</DialogActions>
</Dialog>
</ForwardMessageProvider>
)
}
function ForwardButton() {
const { actions } = use(Composer.Context)
return <Button onPress={actions.submit}>Forward</Button>
}
```
The ForwardButton lives outside the Composer.Frame but still has access to the
submit action because it's within the provider. Even though it's a one-off
component, it can still access the composer's state and actions from outside the
UI itself.
**Key insight:** Components that need shared state don't have to be visually
nested inside each other—they just need to be within the same provider.
---
## 3. Implementation Patterns
**Impact: MEDIUM**
Specific techniques for implementing compound components and
context providers.
### 3.1 Create Explicit Component Variants
**Impact: MEDIUM (self-documenting code, no hidden conditionals)**
Instead of one component with many boolean props, create explicit variant
components. Each variant composes the pieces it needs. The code documents
itself.
**Incorrect: one component, many modes**
```tsx
// What does this component actually render?
<Composer
isThread
isEditing={false}
channelId='abc'
showAttachments
showFormatting={false}
/>
```
**Correct: explicit variants**
```tsx
// Immediately clear what this renders
<ThreadComposer channelId="abc" />
// Or
<EditMessageComposer messageId="xyz" />
// Or
<ForwardMessageComposer messageId="123" />
```
Each implementation is unique, explicit and self-contained. Yet they can each
use shared parts.
**Implementation:**
```tsx
function ThreadComposer({ channelId }: { channelId: string }) {
return (
<ThreadProvider channelId={channelId}>
<Composer.Frame>
<Composer.Input />
<AlsoSendToChannelField channelId={channelId} />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
</ThreadProvider>
)
}
function EditMessageComposer({ messageId }: { messageId: string }) {
return (
<EditMessageProvider messageId={messageId}>
<Composer.Frame>
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.CancelEdit />
<Composer.SaveEdit />
</Composer.Footer>
</Composer.Frame>
</EditMessageProvider>
)
}
function ForwardMessageComposer({ messageId }: { messageId: string }) {
return (
<ForwardMessageProvider messageId={messageId}>
<Composer.Frame>
<Composer.Input placeholder="Add a message, if you'd like." />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.Mentions />
</Composer.Footer>
</Composer.Frame>
</ForwardMessageProvider>
)
}
```
Each variant is explicit about:
- What provider/state it uses
- What UI elements it includes
- What actions are available
No boolean prop combinations to reason about. No impossible states.
### 3.2 Prefer Composing Children Over Render Props
**Impact: MEDIUM (cleaner composition, better readability)**
Use `children` for composition instead of `renderX` props. Children are more
readable, compose naturally, and don't require understanding callback
signatures.
**Incorrect: render props**
```tsx
function Composer({
renderHeader,
renderFooter,
renderActions,
}: {
renderHeader?: () => React.ReactNode
renderFooter?: () => React.ReactNode
renderActions?: () => React.ReactNode
}) {
return (
<form>
{renderHeader?.()}
<Input />
{renderFooter ? renderFooter() : <DefaultFooter />}
{renderActions?.()}
</form>
)
}
// Usage is awkward and inflexible
return (
<Composer
renderHeader={() => <CustomHeader />}
renderFooter={() => (
<>
<Formatting />
<Emojis />
</>
)}
renderActions={() => <SubmitButton />}
/>
)
```
**Correct: compound components with children**
```tsx
function ComposerFrame({ children }: { children: React.ReactNode }) {
return <form>{children}</form>
}
function ComposerFooter({ children }: { children: React.ReactNode }) {
return <footer className='flex'>{children}</footer>
}
// Usage is flexible
return (
<Composer.Frame>
<CustomHeader />
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<SubmitButton />
</Composer.Footer>
</Composer.Frame>
)
```
**When render props are appropriate:**
```tsx
// Render props work well when you need to pass data back
<List
data={items}
renderItem={({ item, index }) => <Item item={item} index={index} />}
/>
```
Use render props when the parent needs to provide data or state to the child.
Use children when composing static structure.
---
## 4. React 19 APIs
**Impact: MEDIUM**
React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
### 4.1 React 19 API Changes
**Impact: MEDIUM (cleaner component definitions and context usage)**
> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
**Incorrect: forwardRef in React 19**
```tsx
const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
return <TextInput ref={ref} {...props} />
})
```
**Correct: ref as a regular prop**
```tsx
function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
return <TextInput ref={ref} {...props} />
}
```
**Incorrect: useContext in React 19**
```tsx
const value = useContext(MyContext)
```
**Correct: use instead of useContext**
```tsx
const value = use(MyContext)
```
`use()` can also be called conditionally, unlike `useContext()`.
---
## References
1. [https://react.dev](https://react.dev)
2. [https://react.dev/learn/passing-data-deeply-with-context](https://react.dev/learn/passing-data-deeply-with-context)
3. [https://react.dev/reference/react/use](https://react.dev/reference/react/use)
================================================
FILE: skills/composition-patterns/README.md
================================================
# React Composition Patterns
A structured repository for React composition patterns that scale. These
patterns help avoid boolean prop proliferation by using compound components,
lifting state, and composing internals.
## Structure
- `rules/` - Individual rule files (one per rule)
- `_sections.md` - Section metadata (titles, impacts, descriptions)
- `_template.md` - Template for creating new rules
- `area-description.md` - Individual rule files
- `metadata.json` - Document metadata (version, organization, abstract)
- **`AGENTS.md`** - Compiled output (generated)
## Rules
### Component Architecture (CRITICAL)
- `architecture-avoid-boolean-props.md` - Don't add boolean props to customize
behavior
- `architecture-compound-components.md` - Structure as compound components with
shared context
### State Management (HIGH)
- `state-lift-state.md` - Lift state into provider components
- `state-context-interface.md` - Define clear context interfaces
(state/actions/meta)
- `state-decouple-implementation.md` - Decouple state management from UI
### Implementation Patterns (MEDIUM)
- `patterns-children-over-render-props.md` - Prefer children over renderX props
- `patterns-explicit-variants.md` - Create explicit component variants
## Core Principles
1. **Composition over configuration** — Instead of adding props, let consumers
compose
2. **Lift your state** — State in providers, not trapped in components
3. **Compose your internals** — Subcomponents access context, not props
4. **Explicit variants** — Create ThreadComposer, EditComposer, not Composer
with isThread
## Creating a New Rule
1. Copy `rules/_template.md` to `rules/area-description.md`
2. Choose the appropriate area prefix:
- `architecture-` for Component Architecture
- `state-` for State Management
- `patterns-` for Implementation Patterns
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations
## Impact Levels
- `CRITICAL` - Foundational patterns, prevents unmaintainable code
- `HIGH` - Significant maintainability improvements
- `MEDIUM` - Good practices for cleaner code
================================================
FILE: skills/composition-patterns/SKILL.md
================================================
---
name: vercel-composition-patterns
description:
React composition patterns that scale. Use when refactoring components with
boolean prop proliferation, building flexible component libraries, or
designing reusable APIs. Triggers on tasks involving compound components,
render props, context providers, or component architecture. Includes React 19
API changes.
license: MIT
metadata:
author: vercel
version: '1.0.0'
---
# React Composition Patterns
Composition patterns for building flexible, maintainable React components. Avoid
boolean prop proliferation by using compound components, lifting state, and
composing internals. These patterns make codebases easier for both humans and AI
agents to work with as they scale.
## When to Apply
Reference these guidelines when:
- Refactoring components with many boolean props
- Building reusable component libraries
- Designing flexible component APIs
- Reviewing component architecture
- Working with compound components or context providers
## Rule Categories by Priority
| Priority | Category | Impact | Prefix |
| -------- | ----------------------- | ------ | --------------- |
| 1 | Component Architecture | HIGH | `architecture-` |
| 2 | State Management | MEDIUM | `state-` |
| 3 | Implementation Patterns | MEDIUM | `patterns-` |
| 4 | React 19 APIs | MEDIUM | `react19-` |
## Quick Reference
### 1. Component Architecture (HIGH)
- `architecture-avoid-boolean-props` - Don't add boolean props to customize
behavior; use composition
- `architecture-compound-components` - Structure complex components with shared
context
### 2. State Management (MEDIUM)
- `state-decouple-implementation` - Provider is the only place that knows how
state is managed
- `state-context-interface` - Define generic interface with state, actions, meta
for dependency injection
- `state-lift-state` - Move state into provider components for sibling access
### 3. Implementation Patterns (MEDIUM)
- `patterns-explicit-variants` - Create explicit variant components instead of
boolean modes
- `patterns-children-over-render-props` - Use children for composition instead
of renderX props
### 4. React 19 APIs (MEDIUM)
> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.
- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`
## How to Use
Read individual rule files for detailed explanations and code examples:
```
rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md
```
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
## Full Compiled Document
For the complete guide with all rules expanded: `AGENTS.md`
================================================
FILE: skills/composition-patterns/metadata.json
================================================
{
"version": "1.0.0",
"organization": "Engineering",
"date": "January 2026",
"abstract": "Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.",
"references": [
"https://react.dev",
"https://react.dev/learn/passing-data-deeply-with-context",
"https://react.dev/reference/react/use"
]
}
================================================
FILE: skills/composition-patterns/rules/_sections.md
================================================
# Sections
This file defines all sections, their ordering, impact levels, and descriptions.
The section ID (in parentheses) is the filename prefix used to group rules.
---
## 1. Component Architecture (architecture)
**Impact:** HIGH
**Description:** Fundamental patterns for structuring components to avoid prop
proliferation and enable flexible composition.
## 2. State Management (state)
**Impact:** MEDIUM
**Description:** Patterns for lifting state and managing shared context across
composed components.
## 3. Implementation Patterns (patterns)
**Impact:** MEDIUM
**Description:** Specific techniques for implementing compound components and
context providers.
## 4. React 19 APIs (react19)
**Impact:** MEDIUM
**Description:** React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
================================================
FILE: skills/composition-patterns/rules/_template.md
================================================
---
title: Rule Title Here
impact: MEDIUM
impactDescription: brief description of impact
tags: composition, components
---
## Rule Title Here
Brief explanation of the rule and why it matters.
**Incorrect:**
```tsx
// Bad code example
```
**Correct:**
```tsx
// Good code example
```
Reference: [Link](https://example.com)
================================================
FILE: skills/composition-patterns/rules/architecture-avoid-boolean-props.md
================================================
---
title: Avoid Boolean Prop Proliferation
impact: CRITICAL
impactDescription: prevents unmaintainable component variants
tags: composition, props, architecture
---
## Avoid Boolean Prop Proliferation
Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
component behavior. Each boolean doubles possible states and creates
unmaintainable conditional logic. Use composition instead.
**Incorrect (boolean props create exponential complexity):**
```tsx
function Composer({
onSubmit,
isThread,
channelId,
isDMThread,
dmId,
isEditing,
isForwarding,
}: Props) {
return (
<form>
<Header />
<Input />
{isDMThread ? (
<AlsoSendToDMField id={dmId} />
) : isThread ? (
<AlsoSendToChannelField id={channelId} />
) : null}
{isEditing ? (
<EditActions />
) : isForwarding ? (
<ForwardActions />
) : (
<DefaultActions />
)}
<Footer onSubmit={onSubmit} />
</form>
)
}
```
**Correct (composition eliminates conditionals):**
```tsx
// Channel composer
function ChannelComposer() {
return (
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<Composer.Footer>
<Composer.Attachments />
<Composer.Formatting />
<Composer.Emojis />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
)
}
// Thread composer - adds "also send to channel" field
function ThreadComposer({ channelId }: { channelId: string }) {
return (
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<AlsoSendToChannelField id={channelId} />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
)
}
// Edit composer - different footer actions
function EditComposer() {
return (
<Composer.Frame>
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.CancelEdit />
<Composer.SaveEdit />
</Composer.Footer>
</Composer.Frame>
)
}
```
Each variant is explicit about what it renders. We can share internals without
sharing a single monolithic parent.
================================================
FILE: skills/composition-patterns/rules/architecture-compound-components.md
================================================
---
title: Use Compound Components
impact: HIGH
impactDescription: enables flexible composition without prop drilling
tags: composition, compound-components, architecture
---
## Use Compound Components
Structure complex components as compound components with a shared context. Each
subcomponent accesses shared state via context, not props. Consumers compose the
pieces they need.
**Incorrect (monolithic component with render props):**
```tsx
function Composer({
renderHeader,
renderFooter,
renderActions,
showAttachments,
showFormatting,
showEmojis,
}: Props) {
return (
<form>
{renderHeader?.()}
<Input />
{showAttachments && <Attachments />}
{renderFooter ? (
renderFooter()
) : (
<Footer>
{showFormatting && <Formatting />}
{showEmojis && <Emojis />}
{renderActions?.()}
</Footer>
)}
</form>
)
}
```
**Correct (compound components with shared context):**
```tsx
const ComposerContext = createContext<ComposerContextValue | null>(null)
function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
return (
<ComposerContext value={{ state, actions, meta }}>
{children}
</ComposerContext>
)
}
function ComposerFrame({ children }: { children: React.ReactNode }) {
return <form>{children}</form>
}
function ComposerInput() {
const {
state,
actions: { update },
meta: { inputRef },
} = use(ComposerContext)
return (
<TextInput
ref={inputRef}
value={state.input}
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
/>
)
}
function ComposerSubmit() {
const {
actions: { submit },
} = use(ComposerContext)
return <Button onPress={submit}>Send</Button>
}
// Export as compound component
const Composer = {
Provider: ComposerProvider,
Frame: ComposerFrame,
Input: ComposerInput,
Submit: ComposerSubmit,
Header: ComposerHeader,
Footer: ComposerFooter,
Attachments: ComposerAttachments,
Formatting: ComposerFormatting,
Emojis: ComposerEmojis,
}
```
**Usage:**
```tsx
<Composer.Provider state={state} actions={actions} meta={meta}>
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
</Composer.Provider>
```
Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
================================================
FILE: skills/composition-patterns/rules/patterns-children-over-render-props.md
================================================
---
title: Prefer Composing Children Over Render Props
impact: MEDIUM
impactDescription: cleaner composition, better readability
tags: composition, children, render-props
---
## Prefer Children Over Render Props
Use `children` for composition instead of `renderX` props. Children are more
readable, compose naturally, and don't require understanding callback
signatures.
**Incorrect (render props):**
```tsx
function Composer({
renderHeader,
renderFooter,
renderActions,
}: {
renderHeader?: () => React.ReactNode
renderFooter?: () => React.ReactNode
renderActions?: () => React.ReactNode
}) {
return (
<form>
{renderHeader?.()}
<Input />
{renderFooter ? renderFooter() : <DefaultFooter />}
{renderActions?.()}
</form>
)
}
// Usage is awkward and inflexible
return (
<Composer
renderHeader={() => <CustomHeader />}
renderFooter={() => (
<>
<Formatting />
<Emojis />
</>
)}
renderActions={() => <SubmitButton />}
/>
)
```
**Correct (compound components with children):**
```tsx
function ComposerFrame({ children }: { children: React.ReactNode }) {
return <form>{children}</form>
}
function ComposerFooter({ children }: { children: React.ReactNode }) {
return <footer className='flex'>{children}</footer>
}
// Usage is flexible
return (
<Composer.Frame>
<CustomHeader />
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<SubmitButton />
</Composer.Footer>
</Composer.Frame>
)
```
**When render props are appropriate:**
```tsx
// Render props work well when you need to pass data back
<List
data={items}
renderItem={({ item, index }) => <Item item={item} index={index} />}
/>
```
Use render props when the parent needs to provide data or state to the child.
Use children when composing static structure.
================================================
FILE: skills/composition-patterns/rules/patterns-explicit-variants.md
================================================
---
title: Create Explicit Component Variants
impact: MEDIUM
impactDescription: self-documenting code, no hidden conditionals
tags: composition, variants, architecture
---
## Create Explicit Component Variants
Instead of one component with many boolean props, create explicit variant
components. Each variant composes the pieces it needs. The code documents
itself.
**Incorrect (one component, many modes):**
```tsx
// What does this component actually render?
<Composer
isThread
isEditing={false}
channelId='abc'
showAttachments
showFormatting={false}
/>
```
**Correct (explicit variants):**
```tsx
// Immediately clear what this renders
<ThreadComposer channelId="abc" />
// Or
<EditMessageComposer messageId="xyz" />
// Or
<ForwardMessageComposer messageId="123" />
```
Each implementation is unique, explicit and self-contained. Yet they can each
use shared parts.
**Implementation:**
```tsx
function ThreadComposer({ channelId }: { channelId: string }) {
return (
<ThreadProvider channelId={channelId}>
<Composer.Frame>
<Composer.Input />
<AlsoSendToChannelField channelId={channelId} />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
</ThreadProvider>
)
}
function EditMessageComposer({ messageId }: { messageId: string }) {
return (
<EditMessageProvider messageId={messageId}>
<Composer.Frame>
<Composer.Input />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.CancelEdit />
<Composer.SaveEdit />
</Composer.Footer>
</Composer.Frame>
</EditMessageProvider>
)
}
function ForwardMessageComposer({ messageId }: { messageId: string }) {
return (
<ForwardMessageProvider messageId={messageId}>
<Composer.Frame>
<Composer.Input placeholder="Add a message, if you'd like." />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
<Composer.Mentions />
</Composer.Footer>
</Composer.Frame>
</ForwardMessageProvider>
)
}
```
Each variant is explicit about:
- What provider/state it uses
- What UI elements it includes
- What actions are available
No boolean prop combinations to reason about. No impossible states.
================================================
FILE: skills/composition-patterns/rules/react19-no-forwardref.md
================================================
---
title: React 19 API Changes
impact: MEDIUM
impactDescription: cleaner component definitions and context usage
tags: react19, refs, context, hooks
---
## React 19 API Changes
> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
**Incorrect (forwardRef in React 19):**
```tsx
const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
return <TextInput ref={ref} {...props} />
})
```
**Correct (ref as a regular prop):**
```tsx
function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
return <TextInput ref={ref} {...props} />
}
```
**Incorrect (useContext in React 19):**
```tsx
const value = useContext(MyContext)
```
**Correct (use instead of useContext):**
```tsx
const value = use(MyContext)
```
`use()` can also be called conditionally, unlike `useContext()`.
================================================
FILE: skills/composition-patterns/rules/state-context-interface.md
================================================
---
title: Define Generic Context Interfaces for Dependency Injection
impact: HIGH
impactDescription: enables dependency-injectable state across use-cases
tags: composition, context, state, typescript, dependency-injection
---
## Define Generic Context Interfaces for Dependency Injection
Define a **generic interface** for your component context with three parts:
`state`, `actions`, and `meta`. This interface is a contract that any provider
can implement—enabling the same UI components to work with completely different
state implementations.
**Core principle:** Lift state, compose internals, make state
dependency-injectable.
**Incorrect (UI coupled to specific state implementation):**
```tsx
function ComposerInput() {
// Tightly coupled to a specific hook
const { input, setInput } = useChannelComposerState()
return <TextInput value={input} onChangeText={setInput} />
}
```
**Correct (generic interface enables dependency injection):**
```tsx
// Define a GENERIC interface that any provider can implement
interface ComposerState {
input: string
attachments: Attachment[]
isSubmitting: boolean
}
interface ComposerActions {
update: (updater: (state: ComposerState) => ComposerState) => void
submit: () => void
}
interface ComposerMeta {
inputRef: React.RefObject<TextInput>
}
interface ComposerContextValue {
state: ComposerState
actions: ComposerActions
meta: ComposerMeta
}
const ComposerContext = createContext<ComposerContextValue | null>(null)
```
**UI components consume the interface, not the implementation:**
```tsx
function ComposerInput() {
const {
state,
actions: { update },
meta,
} = use(ComposerContext)
// This component works with ANY provider that implements the interface
return (
<TextInput
ref={meta.inputRef}
value={state.input}
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
/>
)
}
```
**Different providers implement the same interface:**
```tsx
// Provider A: Local state for ephemeral forms
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
const [state, setState] = useState(initialState)
const inputRef = useRef(null)
const submit = useForwardMessage()
return (
<ComposerContext
value={{
state,
actions: { update: setState, submit },
meta: { inputRef },
}}
>
{children}
</ComposerContext>
)
}
// Provider B: Global synced state for channels
function ChannelProvider({ channelId, children }: Props) {
const { state, update, submit } = useGlobalChannel(channelId)
const inputRef = useRef(null)
return (
<ComposerContext
value={{
state,
actions: { update, submit },
meta: { inputRef },
}}
>
{children}
</ComposerContext>
)
}
```
**The same composed UI works with both:**
```tsx
// Works with ForwardMessageProvider (local state)
<ForwardMessageProvider>
<Composer.Frame>
<Composer.Input />
<Composer.Submit />
</Composer.Frame>
</ForwardMessageProvider>
// Works with ChannelProvider (global synced state)
<ChannelProvider channelId="abc">
<Composer.Frame>
<Composer.Input />
<Composer.Submit />
</Composer.Frame>
</ChannelProvider>
```
**Custom UI outside the component can access state and actions:**
The provider boundary is what matters—not the visual nesting. Components that
need shared state don't have to be inside the `Composer.Frame`. They just need
to be within the provider.
```tsx
function ForwardMessageDialog() {
return (
<ForwardMessageProvider>
<Dialog>
{/* The composer UI */}
<Composer.Frame>
<Composer.Input placeholder="Add a message, if you'd like." />
<Composer.Footer>
<Composer.Formatting />
<Composer.Emojis />
</Composer.Footer>
</Composer.Frame>
{/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
<MessagePreview />
{/* Actions at the bottom of the dialog */}
<DialogActions>
<CancelButton />
<ForwardButton />
</DialogActions>
</Dialog>
</ForwardMessageProvider>
)
}
// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
function ForwardButton() {
const {
actions: { submit },
} = use(ComposerContext)
return <Button onPress={submit}>Forward</Button>
}
// This preview lives OUTSIDE Composer.Frame but can read composer's state!
function MessagePreview() {
const { state } = use(ComposerContext)
return <Preview message={state.input} attachments={state.attachments} />
}
```
The `ForwardButton` and `MessagePreview` are not visually inside the composer
box, but they can still access its state and actions. This is the power of
lifting state into providers.
The UI is reusable bits you compose together. The state is dependency-injected
by the provider. Swap the provider, keep the UI.
================================================
FILE: skills/composition-patterns/rules/state-decouple-implementation.md
================================================
---
title: Decouple State Management from UI
impact: MEDIUM
impactDescription: enables swapping state implementations without changing UI
tags: composition, state, architecture
---
## Decouple State Management from UI
The provider component should be the only place that knows how state is managed.
UI components consume the context interface—they don't know if state comes from
useState, Zustand, or a server sync.
**Incorrect (UI coupled to state implementation):**
```tsx
function ChannelComposer({ channelId }: { channelId: string }) {
// UI component knows about global state implementation
const state = useGlobalChannelState(channelId)
const { submit, updateInput } = useChannelSync(channelId)
return (
<Composer.Frame>
<Composer.Input
value={state.input}
onChange={(text) => sync.updateInput(text)}
/>
<Composer.Submit onPress={() => sync.submit()} />
</Composer.Frame>
)
}
```
**Correct (state management isolated in provider):**
```tsx
// Provider handles all state management details
function ChannelProvider({
channelId,
children,
}: {
channelId: string
children: React.ReactNode
}) {
const { state, update, submit } = useGlobalChannel(channelId)
const inputRef = useRef(null)
return (
<Composer.Provider
state={state}
actions={{ update, submit }}
meta={{ inputRef }}
>
{children}
</Composer.Provider>
)
}
// UI component only knows about the context interface
function ChannelComposer() {
return (
<Composer.Frame>
<Composer.Header />
<Composer.Input />
<Composer.Footer>
<Composer.Submit />
</Composer.Footer>
</Composer.Frame>
)
}
// Usage
function Channel({ channelId }: { channelId: string }) {
return (
<ChannelProvider channelId={channelId}>
<ChannelComposer />
</ChannelProvider>
)
}
```
**Different providers, same UI:**
```tsx
// Local state for ephemeral forms
function ForwardMessageProvider({ children }) {
const [state, setState] = useState(initialState)
const forwardMessage = useForwardMessage()
return (
<Composer.Provider
state={state}
actions={{ update: setState, submit: forwardMessage }}
>
{children}
</Composer.Provider>
)
}
// Global synced state for channels
function ChannelProvider({ channelId, children }) {
const { state, update, submit } = useGlobalChannel(channelId)
return (
<Composer.Provider state={state} actions={{ update, submit }}>
{children}
</Composer.Provider>
)
}
```
The same `Composer.Input` component works with both providers because it only
depends on the context interface, not the implementation.
================================================
FILE: skills/composition-patterns/rules/state-lift-state.md
================================================
---
title: Lift State into Provider Components
impact: HIGH
impactDescription: enables state sharing outside component boundaries
tags: composition, state, context, providers
---
## Lift State into Provider Components
Move state management into dedicated provider components. This allows sibling
components outside the main UI to access and modify state without prop drilling
or awkward refs.
**Incorrect (state trapped inside component):**
```tsx
function ForwardMessageComposer() {
const [state, setState] = useState(initialState)
const forwardMessage = useForwardMessage()
return (
<Composer.Frame>
<Composer.Input />
<Composer.Footer />
</Composer.Frame>
)
}
// Problem: How does this button access composer state?
function ForwardMessageDialog() {
return (
<Dialog>
<ForwardMessageComposer />
<MessagePreview /> {/* Needs composer state */}
<DialogActions>
<CancelButton />
<ForwardButton /> {/* Needs to call submit */}
</DialogActions>
</Dialog>
)
}
```
**Incorrect (useEffect to sync state up):**
```tsx
function ForwardMessageDialog() {
const [input, setInput] = useState('')
return (
<Dialog>
<ForwardMessageComposer onInputChange={setInput} />
<MessagePreview input={input} />
</Dialog>
)
}
function ForwardMessageComposer({ onInputChange }) {
const [state, setState] = useState(initialState)
useEffect(() => {
onInputChange(state.input) // Sync on every change 😬
}, [state.input])
}
```
**Incorrect (reading state from ref on submit):**
```tsx
function ForwardMessageDialog() {
const stateRef = useRef(null)
return (
<Dialog>
<ForwardMessageComposer stateRef={stateRef} />
<ForwardButton onPress={() => submit(stateRef.current)} />
</Dialog>
)
}
```
**Correct (state lifted to provider):**
```tsx
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
const [state, setState] = useState(initialState)
const forwardMessage = useForwardMessage()
const inputRef = useRef(null)
return (
<Composer.Provider
state={state}
actions={{ update: setState, submit: forwardMessage }}
meta={{ inputRef }}
>
{children}
</Composer.Provider>
)
}
function ForwardMessageDialog() {
return (
<ForwardMessageProvider>
<Dialog>
<ForwardMessageComposer />
<MessagePreview /> {/* Custom components can access state and actions */}
<DialogActions>
<CancelButton />
<ForwardButton /> {/* Custom components can access state and actions */}
</DialogActions>
</Dialog>
</ForwardMessageProvider>
)
}
function ForwardButton() {
const { actions } = use(Composer.Context)
return <Button onPress={actions.submit}>Forward</Button>
}
```
The ForwardButton lives outside the Composer.Frame but still has access to the
submit action because it's within the provider. Even though it's a one-off
component, it can still access the composer's state and actions from outside the
UI itself.
**Key insight:** Components that need shared state don't have to be visually
nested inside each other—they just need to be within the same provider.
================================================
FILE: skills/deploy-to-vercel/SKILL.md
================================================
---
name: deploy-to-vercel
description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
metadata:
author: vercel
version: "3.0.0"
---
# Deploy to Vercel
Deploy any project to Vercel. **Always deploy as preview** (not production) unless the user explicitly asks for production.
The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.
## Step 1: Gather Project State
Run all four checks before deciding which method to use:
```bash
# 1. Check for a git remote
git remote get-url origin 2>/dev/null
# 2. Check if locally linked to a Vercel project (either file means linked)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
# 3. Check if the Vercel CLI is installed and authenticated
vercel whoami 2>/dev/null
# 4. List available teams (if authenticated)
vercel teams list --format json 2>/dev/null
```
### Team selection
If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.
Pass the team slug via `--scope` on all subsequent CLI commands (`vercel deploy`, `vercel link`, `vercel inspect`, etc.):
```bash
vercel deploy [path] -y --no-wait --scope <team-slug>
```
If the project is already linked (`.vercel/project.json` or `.vercel/repo.json` exists), the `orgId` in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.
**About the `.vercel/` directory:** A linked project has either:
- `.vercel/project.json` — created by `vercel link` (single project linking). Contains `projectId` and `orgId`.
- `.vercel/repo.json` — created by `vercel link --repo` (repo-based linking). Contains `orgId`, `remoteName`, and a `projects` array mapping directories to Vercel project IDs.
Either file means the project is linked. Check for both.
**Do NOT** use `vercel project inspect`, `vercel ls`, or `vercel link` to detect state in an unlinked directory — without a `.vercel/` config, they will interactively prompt (or with `--yes`, silently link as a side-effect). Only `vercel whoami` is safe to run anywhere.
## Step 2: Choose a Deploy Method
### Linked (`.vercel/` exists) + has git remote → Git Push
This is the ideal state. The project is linked and has git integration.
1. **Ask the user before pushing.** Never push without explicit approval:
```
This project is connected to Vercel via git. I can commit and push to
trigger a deployment. Want me to proceed?
```
2. **Commit and push:**
```bash
git add .
git commit -m "deploy: <description of changes>"
git push
```
Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually `main`) gets a production deployment.
3. **Retrieve the preview URL.** If the CLI is authenticated:
```bash
sleep 5
vercel ls --format json
```
The JSON output has a `deployments` array. Find the latest entry — its `url` field is the preview URL.
If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.
---
### Linked (`.vercel/` exists) + no git remote → `vercel deploy`
The project is linked but there's no git repo. Deploy directly with the CLI.
```bash
vercel deploy [path] -y --no-wait
```
Use `--no-wait` so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:
```bash
vercel inspect <deployment-url>
```
For production deploys (only if user explicitly asks):
```bash
vercel deploy [path] --prod -y --no-wait
```
---
### Not linked + CLI is authenticated → Link first, then deploy
The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.
1. **Ask the user which team to deploy to.** Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.
2. **Once a team is selected, proceed directly to linking.** Tell the user what will happen but do not ask for separate confirmation:
```
Linking this project to <team name> on Vercel. This will create a Vercel
project to deploy to and enable automatic deployments on future git pushes.
```
3. **If a git remote exists**, use repo-based linking with the selected team scope:
```bash
vercel link --repo --scope <team-slug>
```
This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates `.vercel/repo.json`. This is much more reliable than `vercel link` (without `--repo`), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
**If there is no git remote**, fall back to standard linking:
```bash
vercel link --scope <team-slug>
```
This prompts the user to select or create a project. It creates `.vercel/project.json`.
4. **Then deploy using the best available method:**
- If a git remote exists → commit and push (see git push method above)
- If no git remote → `vercel deploy [path] -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status
---
### Not linked + CLI not authenticated → Install, auth, link, deploy
The Vercel CLI isn't set up at all.
1. **Install the CLI (if not already installed):**
```bash
npm install -g vercel
```
2. **Authenticate:**
```bash
vercel login
```
The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the **no-auth fallback** below.
3. **Ask which team to deploy to** — present team slugs from `vercel teams list --format json` as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.
4. **Link the project** with the selected team scope (use `--repo` if a git remote exists, plain `vercel link` otherwise):
```bash
vercel link --repo --scope <team-slug> # if git remote exists
vercel link --scope <team-slug> # if no git remote
```
5. **Deploy** using the best available method (git push if remote exists, otherwise `vercel deploy -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status).
---
### No-Auth Fallback — claude.ai sandbox
**When to use:** Last resort when the CLI can't be installed or authenticated in the claude.ai sandbox. This requires no authentication — it returns a **Preview URL** (live site) and a **Claim URL** (transfer to your Vercel account).
```bash
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
```
**Arguments:**
- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
**Examples:**
```bash
# Deploy current directory
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
# Deploy specific project
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
# Deploy existing tarball
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
```
The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.
**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
---
### No-Auth Fallback — Codex sandbox
**When to use:** In the Codex sandbox where the CLI may not be authenticated. Codex runs in a sandboxed environment by default — try the CLI first, and fall back to the deploy script if auth fails.
1. **Check whether the Vercel CLI is installed** (no escalation needed for this check):
```bash
command -v vercel
```
2. **If `vercel` is installed**, try deploying with the CLI:
```bash
vercel deploy [path] -y --no-wait
```
3. **If `vercel` is not installed, or the CLI fails with "No existing credentials found"**, use the fallback script:
```bash
skill_dir="<path-to-skill>"
# Deploy current directory
bash "$skill_dir/resources/deploy-codex.sh"
# Deploy specific project
bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
# Deploy existing tarball
bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
```
The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
**Escalated network access:** Only escalate the actual deploy command if sandboxing blocks the network call (`sandbox_permissions=require_escalated`). Do **not** escalate the `command -v vercel` check.
---
## Agent-Specific Notes
### Claude Code / terminal-based agents
You have full shell access. Do NOT use the `/mnt/skills/` path. Follow the decision flow above using the CLI directly.
For the no-auth fallback, run the deploy script from the skill's installed location:
```bash
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
```
The path may vary depending on where the user installed the skill.
### Sandboxed environments (claude.ai)
You likely cannot run `vercel login` or `git push`. Go directly to the **no-auth fallback — claude.ai sandbox**.
### Codex
Codex runs in a sandbox. Check if the CLI is available first, then fall back to the deploy script. Go to the **no-auth fallback — Codex sandbox**.
---
## Output
Always show the user the deployment URL.
- **Git push:** Use `vercel ls --format json` to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
- **CLI deploy:** Show the URL returned by `vercel deploy --no-wait`. Use `vercel inspect <url>` to check build status and report it to the user.
- **No-auth fallback:** Show both the preview URL and the claim URL:
```
Deployment successful!
Preview URL: https://my-app-abc123.vercel.app
Claim URL: https://vercel.com/claim-deployment?code=...
View your site at the Preview URL.
To transfer this deployment to your Vercel account, visit the Claim URL.
```
**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
---
## Troubleshooting
### Network Egress Error (claude.ai)
If deployment fails due to network restrictions on claude.ai, tell the user:
```
Deployment failed due to network restrictions. To fix this:
1. Go to https://claude.ai/settings/capabilities
2. Add *.vercel.com to the allowed domains
3. Try deploying again
```
### Escalated Network Access (Codex / sandboxed environments)
If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (`sandbox_permissions=require_escalated`). Do not escalate the initial CLI availability check — only escalate the actual deploy command.
Example guidance to the user:
```
The deploy needs escalated network access to deploy to Vercel. I can rerun
the command with escalated permissions — want me to proceed?
```
### CLI Auth Failure
If `vercel login` or `vercel deploy` fails with authentication errors, fall back to the no-auth deploy script (claude.ai or Codex variant, depending on the environment).
================================================
FILE: skills/deploy-to-vercel/resources/deploy-codex.sh
================================================
#!/bin/bash
# Vercel Deployment Script for Codex (via claimable deploy endpoint)
# Usage: ./deploy-codex.sh [project-path]
# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
set -euo pipefail
DEPLOY_ENDPOINT="https://codex-deploy-skills.vercel.sh/api/deploy"
# Detect framework from package.json
detect_framework() {
local pkg_json="$1"
if [ ! -f "$pkg_json" ]; then
echo "null"
return
fi
local content=$(cat "$pkg_json")
# Helper to check if a package exists in dependencies or devDependencies.
# Use exact matching by default, with a separate prefix matcher for scoped
# package families like "@remix-run/".
has_dep_exact() {
echo "$content" | grep -q "\"$1\""
}
has_dep_prefix() {
echo "$content" | grep -q "\"$1"
}
# Order matters - check more specific frameworks first
# Blitz
if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
# Next.js
if has_dep_exact "next"; then echo "nextjs"; return; fi
# Gatsby
if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
# Remix
if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
# React Router (v7 framework mode)
if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
# TanStack Start
if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
# Astro
if has_dep_exact "astro"; then echo "astro"; return; fi
# Hydrogen (Shopify)
if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
# SvelteKit
if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
# Svelte (standalone)
if has_dep_exact "svelte"; then echo "svelte"; return; fi
# Nuxt
if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
# Vue with Vitepress
if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
# Vue with Vuepress
if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
# Gridsome
if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
# SolidStart
if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
# Docusaurus
if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
# RedwoodJS
if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
# Hexo
if has_dep_exact "hexo"; then echo "hexo"; return; fi
# Eleventy
if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
# Angular / Ionic Angular
if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
if has_dep_exact "@angular/core"; then echo "angular"; return; fi
# Ionic React
if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
# Create React App
if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
# Ember
if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
# Dojo
if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
# Polymer
if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
# Preact
if has_dep_exact "preact"; then echo "preact"; return; fi
# Stencil
if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
# UmiJS
if has_dep_exact "umi"; then echo "umijs"; return; fi
# Sapper (legacy Svelte)
if has_dep_exact "sapper"; then echo "sapper"; return; fi
# Saber
if has_dep_exact "saber"; then echo "saber"; return; fi
# Sanity
if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
# Storybook
if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
# NestJS
if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
# Elysia
if has_dep_exact "elysia"; then echo "elysia"; return; fi
# Hono
if has_dep_exact "hono"; then echo "hono"; return; fi
# Fastify
if has_dep_exact "fastify"; then echo "fastify"; return; fi
# h3
if has_dep_exact "h3"; then echo "h3"; return; fi
# Nitro
if has_dep_exact "nitropack"; then echo "nitro"; return; fi
# Express
if has_dep_exact "express"; then echo "express"; return; fi
# Vite (generic - check last among JS frameworks)
if has_dep_exact "vite"; then echo "vite"; return; fi
# Parcel
if has_dep_exact "parcel"; then echo "parcel"; return; fi
# No framework detected
echo "null"
}
# Parse arguments
INPUT_PATH="${1:-.}"
# Create temp directory for packaging
TEMP_DIR=$(mktemp -d)
TARBALL="$TEMP_DIR/project.tgz"
STAGING_DIR="$TEMP_DIR/staging"
CLEANUP_TEMP=true
cleanup() {
if [ "$CLEANUP_TEMP" = true ]; then
rm -rf "$TEMP_DIR"
fi
}
trap cleanup EXIT
echo "Preparing deployment..." >&2
# Check if input is a .tgz file or a directory
FRAMEWORK="null"
if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
# Input is already a tarball, use it directly
echo "Using provided tarball..." >&2
TARBALL="$INPUT_PATH"
CLEANUP_TEMP=false
# Can't detect framework from tarball, leave as null
elif [ -d "$INPUT_PATH" ]; then
# Input is a directory, need to tar it
PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
# Detect framework from package.json
FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
# Stage files into a temporary directory to avoid mutating the source tree.
mkdir -p "$STAGING_DIR"
echo "Staging project files..." >&2
tar -C "$PROJECT_PATH" \
--exclude='node_modules' \
--exclude='.git' \
--exclude='.env' \
--exclude='.env.*' \
-cf - . | tar -C "$STAGING_DIR" -xf -
# Check if this is a static HTML project (no package.json)
if [ ! -f "$PROJECT_PATH/package.json" ]; then
# Find HTML files in root
HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
# If there's exactly one HTML file and it's not index.html, rename it
if [ "$HTML_COUNT" -eq 1 ]; then
HTML_FILE=$(echo "$HTML_FILES" | head -1)
BASENAME=$(basename "$HTML_FILE")
if [ "$BASENAME" != "index.html" ]; then
echo "Renaming $BASENAME to index.html..." >&2
mv "$HTML_FILE" "$STAGING_DIR/index.html"
fi
fi
fi
# Create tarball from the staging directory
echo "Creating deployment package..." >&2
tar -czf "$TARBALL" -C "$STAGING_DIR" .
else
echo "Error: Input must be a directory or a .tgz file" >&2
exit 1
fi
if [ "$FRAMEWORK" != "null" ]; then
echo "Detected framework: $FRAMEWORK" >&2
fi
# Deploy
echo "Deploying..." >&2
RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
# Check for error in response
if echo "$RESPONSE" | grep -q '"error"'; then
ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
echo "Error: $ERROR_MSG" >&2
exit 1
fi
# Extract URLs from response
PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
if [ -z "$PREVIEW_URL" ]; then
echo "Error: Could not extract preview URL from response" >&2
echo "$RESPONSE" >&2
exit 1
fi
echo "Deployment started. Waiting for build to complete..." >&2
echo "Preview URL: $PREVIEW_URL" >&2
# Poll the preview URL until it returns a non-5xx response (5xx = still building)
MAX_ATTEMPTS=60 # 5 minutes max (60 * 5 seconds)
ATTEMPT=0
while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
if [ "$HTTP_STATUS" -eq 200 ]; then
echo "" >&2
echo "Deployment ready!" >&2
break
elif [ "$HTTP_STATUS" -ge 500 ]; then
# 5xx means still building/deploying
echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
sleep 5
ATTEMPT=$((ATTEMPT + 1))
elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
# 4xx might be an error or the app itself returns 4xx - it's responding
echo "" >&2
echo "Deployment ready (returned $HTTP_STATUS)!" >&2
break
else
# Any other status, assume it's ready
echo "" >&2
echo "Deployment ready!" >&2
break
fi
done
if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
echo "" >&2
echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
fi
echo "" >&2
echo "Preview URL: $PREVIEW_URL" >&2
echo "Claim URL: $CLAIM_URL" >&2
echo "" >&2
# Output JSON for programmatic use
echo "$RESPONSE"
================================================
FILE: skills/deploy-to-vercel/resources/deploy.sh
================================================
#!/bin/bash
# Vercel Deployment Script (via claimable deploy endpoint)
# Usage: ./deploy.sh [project-path]
# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
set -euo pipefail
DEPLOY_ENDPOINT="https://claude-skills-deploy.vercel.com/api/deploy"
# Detect framework from package.json
detect_framework() {
local pkg_json="$1"
if [ ! -f "$pkg_json" ]; then
echo "null"
return
fi
local content=$(cat "$pkg_json")
# Helper to check if a package exists in dependencies or devDependencies.
# Use exact matching by default, with a separate prefix matcher for scoped
# package families like "@remix-run/".
has_dep_exact() {
echo "$content" | grep -q "\"$1\""
}
has_dep_prefix() {
echo "$content" | grep -q "\"$1"
}
# Order matters - check more specific frameworks first
# Blitz
if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
# Next.js
if has_dep_exact "next"; then echo "nextjs"; return; fi
# Gatsby
if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
# Remix
if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
# React Router (v7 framework mode)
if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
# TanStack Start
if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
# Astro
if has_dep_exact "astro"; then echo "astro"; return; fi
# Hydrogen (Shopify)
if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
# SvelteKit
if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
# Svelte (standalone)
if has_dep_exact "svelte"; then echo "svelte"; return; fi
# Nuxt
if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
# Vue with Vitepress
if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
# Vue with Vuepress
if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
# Gridsome
if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
# SolidStart
if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
# Docusaurus
if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
# RedwoodJS
if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
# Hexo
if has_dep_exact "hexo"; then echo "hexo"; return; fi
# Eleventy
if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
# Angular / Ionic Angular
if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
if has_dep_exact "@angular/core"; then echo "angular"; return; fi
# Ionic React
if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
# Create React App
if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
# Ember
if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
# Dojo
if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
# Polymer
if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
# Preact
if has_dep_exact "preact"; then echo "preact"; return; fi
# Stencil
if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
# UmiJS
if has_dep_exact "umi"; then echo "umijs"; return; fi
# Sapper (legacy Svelte)
if has_dep_exact "sapper"; then echo "sapper"; return; fi
# Saber
if has_dep_exact "saber"; then echo "saber"; return; fi
# Sanity
if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
# Storybook
if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
# NestJS
if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
# Elysia
if has_dep_exact "elysia"; then echo "elysia"; return; fi
# Hono
if has_dep_exact "hono"; then echo "hono"; return; fi
# Fastify
if has_dep_exact "fastify"; then echo "fastify"; return; fi
# h3
if has_dep_exact "h3"; then echo "h3"; return; fi
# Nitro
if has_dep_exact "nitropack"; then echo "nitro"; return; fi
# Express
if has_dep_exact "express"; then echo "express"; return; fi
# Vite (generic - check last among JS frameworks)
if has_dep_exact "vite"; then echo "vite"; return; fi
# Parcel
if has_dep_exact "parcel"; then echo "parcel"; return; fi
# No framework detected
echo "null"
}
# Parse arguments
INPUT_PATH="${1:-.}"
# Create temp directory for packaging
TEMP_DIR=$(mktemp -d)
TARBALL="$TEMP_DIR/project.tgz"
STAGING_DIR="$TEMP_DIR/staging"
CLEANUP_TEMP=true
cleanup() {
if [ "$CLEANUP_TEMP" = true ]; then
rm -rf "$TEMP_DIR"
fi
}
trap cleanup EXIT
echo "Preparing deployment..." >&2
# Check if input is a .tgz file or a directory
FRAMEWORK="null"
if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
# Input is already a tarball, use it directly
echo "Using provided tarball..." >&2
TARBALL="$INPUT_PATH"
CLEANUP_TEMP=false
# Can't detect framework from tarball, leave as null
elif [ -d "$INPUT_PATH" ]; then
# Input is a directory, need to tar it
PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
# Detect framework from package.json
FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
# Stage files into a temporary directory to avoid mutating the source tree.
mkdir -p "$STAGING_DIR"
echo "Staging project files..." >&2
tar -C "$PROJECT_PATH" \
--exclude='node_modules' \
--exclude='.git' \
--exclude='.env' \
--exclude='.env.*' \
-cf - . | tar -C "$STAGING_DIR" -xf -
# Check if this is a static HTML project (no package.json)
if [ ! -f "$PROJECT_PATH/package.json" ]; then
# Find HTML files in root
HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
# If there's exactly one HTML file and it's not index.html, rename it
if [ "$HTML_COUNT" -eq 1 ]; then
HTML_FILE=$(echo "$HTML_FILES" | head -1)
BASENAME=$(basename "$HTML_FILE")
if [ "$BASENAME" != "index.html" ]; then
echo "Renaming $BASENAME to index.html..." >&2
mv "$HTML_FILE" "$STAGING_DIR/index.html"
fi
fi
fi
# Create tarball from the staging directory
echo "Creating deployment package..." >&2
tar -czf "$TARBALL" -C "$STAGING_DIR" .
else
echo "Error: Input must be a directory or a .tgz file" >&2
exit 1
fi
if [ "$FRAMEWORK" != "null" ]; then
echo "Detected framework: $FRAMEWORK" >&2
fi
# Deploy
echo "Deploying..." >&2
RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
# Check for error in response
if echo "$RESPONSE" | grep -q '"error"'; then
ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
echo "Error: $ERROR_MSG" >&2
exit 1
fi
# Extract URLs from response
PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
if [ -z "$PREVIEW_URL" ]; then
echo "Error: Could not extract preview URL from response" >&2
echo "$RESPONSE" >&2
exit 1
fi
echo "Deployment started. Waiting for build to complete..." >&2
echo "Preview URL: $PREVIEW_URL" >&2
# Poll the preview URL until it returns a non-5xx response (5xx = still building)
MAX_ATTEMPTS=60 # 5 minutes max (60 * 5 seconds)
ATTEMPT=0
while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
if [ "$HTTP_STATUS" -eq 200 ]; then
echo "" >&2
echo "Deployment ready!" >&2
break
elif [ "$HTTP_STATUS" -ge 500 ]; then
# 5xx means still building/deploying
echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
sleep 5
ATTEMPT=$((ATTEMPT + 1))
elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
# 4xx might be an error or the app itself returns 4xx - it's responding
echo "" >&2
echo "Deployment ready (returned $HTTP_STATUS)!" >&2
break
else
# Any other status, assume it's ready
echo "" >&2
echo "Deployment ready!" >&2
break
fi
done
if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
echo "" >&2
echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
fi
echo "" >&2
echo "Preview URL: $PREVIEW_URL" >&2
echo "Claim URL: $CLAIM_URL" >&2
echo "" >&2
# Output JSON for programmatic use
echo "$RESPONSE"
================================================
FILE: skills/react-best-practices/AGENTS.md
================================================
# React Best Practices
**Version 1.0.0**
Vercel Engineering
January 2026
> **Note:**
> This document is mainly for agents and LLMs to follow when maintaining,
> generating, or refactoring React and Next.js codebases. Humans
> may also find it useful, but guidance here is optimized for automation
> and consistency by AI-assisted workflows.
---
## 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.
---
## Table of Contents
1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
- 1.1 [Defer Await Until Needed](#11-defer-await-until-needed)
- 1.2 [Dependency-Based Parallelization](#12-dependency-based-parallelization)
- 1.3 [Prevent Waterfall Chains in API Routes](#13-prevent-waterfall-chains-in-api-routes)
- 1.4 [Promise.all() for Independent Operations](#14-promiseall-for-independent-operations)
- 1.5 [Strategic Suspense Boundaries](#15-strategic-suspense-boundaries)
2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
- 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
- 2.2 [Conditional Module Loading](#22-conditional-module-loading)
- 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
- 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
- 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent)
3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
- 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
- 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
- 3.3 [Cross-Request LRU Caching](#33-cross-request-lru-caching)
- 3.4 [Hoist Static I/O to Module Level](#34-hoist-static-io-to-module-level)
- 3.5 [Minimize Serialization at RSC Boundaries](#35-minimize-serialization-at-rsc-boundaries)
- 3.6 [Parallel Data Fetching with Component Composition](#36-parallel-data-fetching-with-component-composition)
- 3.7 [Per-Request Deduplication with React.cache()](#37-per-request-deduplication-with-reactcache)
- 3.8 [Use after() for Non-Blocking Operations](#38-use-after-for-non-blocking-operations)
4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
- 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
- 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
- 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
- 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
- 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering)
- 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point)
- 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
- 5.4 [Don't Define Components Inside Components](#54-dont-define-components-inside-components)
- 5.5 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#55-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
- 5.6 [Extract to Memoized Components](#56-extract-to-memoized-components)
- 5.7 [Narrow Effect Dependencies](#57-narrow-effect-dependencies)
- 5.8 [Put Interaction Logic in Event Handlers](#58-put-interaction-logic-in-event-handlers)
- 5.9 [Split Combined Hook Computations](#59-split-combined-hook-computations)
- 5.10 [Subscribe to Derived State](#510-subscribe-to-derived-state)
- 5.11 [Use Functional setState Updates](#511-use-functional-setstate-updates)
- 5.12 [Use Lazy State Initialization](#512-use-lazy-state-initialization)
- 5.13 [Use Transitions for Non-Urgent Updates](#513-use-transitions-for-non-urgent-updates)
- 5.14 [Use useDeferredValue for Expensive Derived Renders](#514-use-usedeferredvalue-for-expensive-derived-renders)
- 5.15 [Use useRef for Transient Values](#515-use-useref-for-transient-values)
6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
- 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
- 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
- 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
- 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
- 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
- 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches)
- 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide)
- 6.8 [Use defer or async on Script Tags](#68-use-defer-or-async-on-script-tags)
- 6.9 [Use Explicit Conditional Rendering](#69-use-explicit-conditional-rendering)
- 6.10 [Use React DOM Resource Hints](#610-use-react-dom-resource-hints)
- 6.11 [Use useTransition Over Manual Loading States](#611-use-usetransition-over-manual-loading-states)
7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
- 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
- 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
- 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
- 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
- 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
- 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
- 7.7 [Early Length Check for Array Comparisons](#77-early-length-check-for-array-comparisons)
- 7.8 [Early Return from Functions](#78-early-return-from-functions)
- 7.9 [Hoist RegExp Creation](#79-hoist-regexp-creation)
- 7.10 [Use flatMap to Map and Filter in One Pass](#710-use-flatmap-to-map-and-filter-in-one-pass)
- 7.11 [Use Loop for Min/Max Instead of Sort](#711-use-loop-for-minmax-instead-of-sort)
- 7.12 [Use Set/Map for O(1) Lookups](#712-use-setmap-for-o1-lookups)
- 7.13 [Use toSorted() Instead of sort() for Immutability](#713-use-tosorted-instead-of-sort-for-immutability)
8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
- 8.1 [Initialize App Once, Not Per Mount](#81-initialize-app-once-not-per-mount)
- 8.2 [Store Event Handlers in Refs](#82-store-event-handlers-in-refs)
- 8.3 [useEffectEvent for Stable Callback Refs](#83-useeffectevent-for-stable-callback-refs)
---
## 1. Eliminating Waterfalls
**Impact: CRITICAL**
Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
### 1.1 Defer Await Until Needed
**Impact: HIGH (avoids blocking unused code paths)**
Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
**Incorrect: blocks both branches**
```typescript
async function handleRequest(userId: string, skipProcessing: boolean) {
const userData = await fetchUserData(userId)
if (skipProcessing) {
// Returns immediately but still waited for userData
return { skipped: true }
}
// Only this branch uses userData
return processUserData(userData)
}
```
**Correct: only blocks when needed**
```typescript
async function handleRequest(userId: string, skipProcessing: boolean) {
if (skipProcessing) {
// Returns immediately without waiting
return { skipped: true }
}
// Fetch only when needed
const userData = await fetchUserData(userId)
return processUserData(userData)
}
```
**Another example: early return optimization**
```typescript
// Incorrect: always fetches permissions
async function updateResource(resourceId: string, userId: string) {
const permissions = await fetchPermissions(userId)
const resource = await getResource(resourceId)
if (!resource) {
return { error: 'Not found' }
}
if (!permissions.canEdit) {
return { error: 'Forbidden' }
}
return await updateResourceData(resource, permissions)
}
// Correct: fetches only when needed
async function updateResource(resourceId: string, userId: string) {
const resource = await getResource(resourceId)
if (!resource) {
return { error: 'Not found' }
}
const permissions = await fetchPermissions(userId)
if (!permissions.canEdit) {
return { error: 'Forbidden' }
}
return await updateResourceData(resource, permissions)
}
```
This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
### 1.2 Dependency-Based Parallelization
**Impact: CRITICAL (2-10× improvement)**
For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
**Incorrect: profile waits for config unnecessarily**
```typescript
const [user, config] = await Promise.all([
fetchUser(),
fetchConfig()
])
const profile = await fetchProfile(user.id)
```
**Correct: config and profile run in parallel**
```typescript
import { all } from 'better-all'
const { user, config, profile } = await all({
async user() { return fetchUser() },
async config() { return fetchConfig() },
async profile() {
return fetchProfile((await this.$.user).id)
}
})
```
**Alternative without extra dependencies:**
```typescript
const userPromise = fetchUser()
const profilePromise = userPromise.then(user => fetchProfile(user.id))
const [user, config, profile] = await Promise.all([
userPromise,
fetchConfig(),
profilePromise
])
```
We can also create all the promises first, and do `Promise.all()` at the end.
Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
### 1.3 Prevent Waterfall Chains in API Routes
**Impact: CRITICAL (2-10× improvement)**
In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
**Incorrect: config waits for auth, data waits for both**
```typescript
export async function GET(request: Request) {
const session = await auth()
const config = await fetchConfig()
const data = await fetchData(session.user.id)
return Response.json({ data, config })
}
```
**Correct: auth and config start immediately**
```typescript
export async function GET(request: Request) {
const sessionPromise = auth()
const configPromise = fetchConfig()
const session = await sessionPromise
const [config, data] = await Promise.all([
configPromise,
fetchData(session.user.id)
])
return Response.json({ data, config })
}
```
For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
### 1.4 Promise.all() for Independent Operations
**Impact: CRITICAL (2-10× improvement)**
When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
**Incorrect: sequential execution, 3 round trips**
```typescript
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()
```
**Correct: parallel execution, 1 round trip**
```typescript
const [user, posts, comments] = await Promise.all([
fetchUser(),
fetchPosts(),
fetchComments()
])
```
### 1.5 Strategic Suspense Boundaries
**Impact: HIGH (faster initial paint)**
Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
**Incorrect: wrapper blocked by data fetching**
```tsx
async function Page() {
const data = await fetchData() // Blocks entire page
return (
<div>
<div>Sidebar</div>
<div>Header</div>
<div>
<DataDisplay data={data} />
</div>
<div>Footer</div>
</div>
)
}
```
The entire layout waits for data even though only the middle section needs it.
**Correct: wrapper shows immediately, data streams in**
```tsx
function Page() {
return (
<div>
<div>Sidebar</div>
<div>Header</div>
<div>
<Suspense fallback={<Skeleton />}>
<DataDisplay />
</Suspense>
</div>
<div>Footer</div>
</div>
)
}
async function DataDisplay() {
const data = await fetchData() // Only blocks this component
return <div>{data.content}</div>
}
```
Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
**Alternative: share promise across components**
```tsx
function Page() {
// Start fetch immediately, but don't await
const dataPromise = fetchData()
return (
<di
gitextract_uut7bmea/
├── .github/
│ └── workflows/
│ └── react-best-practices-ci.yml
├── .gitignore
├── AGENTS.md
├── README.md
├── packages/
│ └── react-best-practices-build/
│ ├── .gitignore
│ ├── package.json
│ ├── src/
│ │ ├── build.ts
│ │ ├── config.ts
│ │ ├── extract-tests.ts
│ │ ├── migrate.ts
│ │ ├── parser.ts
│ │ ├── types.ts
│ │ └── validate.ts
│ ├── test-cases.json
│ └── tsconfig.json
└── skills/
├── composition-patterns/
│ ├── AGENTS.md
│ ├── README.md
│ ├── SKILL.md
│ ├── metadata.json
│ └── rules/
│ ├── _sections.md
│ ├── _template.md
│ ├── architecture-avoid-boolean-props.md
│ ├── architecture-compound-components.md
│ ├── patterns-children-over-render-props.md
│ ├── patterns-explicit-variants.md
│ ├── react19-no-forwardref.md
│ ├── state-context-interface.md
│ ├── state-decouple-implementation.md
│ └── state-lift-state.md
├── deploy-to-vercel/
│ ├── SKILL.md
│ └── resources/
│ ├── deploy-codex.sh
│ └── deploy.sh
├── react-best-practices/
│ ├── AGENTS.md
│ ├── README.md
│ ├── SKILL.md
│ ├── metadata.json
│ └── rules/
│ ├── _sections.md
│ ├── _template.md
│ ├── advanced-event-handler-refs.md
│ ├── advanced-init-once.md
│ ├── advanced-use-latest.md
│ ├── async-api-routes.md
│ ├── async-defer-await.md
│ ├── async-dependencies.md
│ ├── async-parallel.md
│ ├── async-suspense-boundaries.md
│ ├── bundle-barrel-imports.md
│ ├── bundle-conditional.md
│ ├── bundle-defer-third-party.md
│ ├── bundle-dynamic-imports.md
│ ├── bundle-preload.md
│ ├── client-event-listeners.md
│ ├── client-localstorage-schema.md
│ ├── client-passive-event-listeners.md
│ ├── client-swr-dedup.md
│ ├── js-batch-dom-css.md
│ ├── js-cache-function-results.md
│ ├── js-cache-property-access.md
│ ├── js-cache-storage.md
│ ├── js-combine-iterations.md
│ ├── js-early-exit.md
│ ├── js-flatmap-filter.md
│ ├── js-hoist-regexp.md
│ ├── js-index-maps.md
│ ├── js-length-check-first.md
│ ├── js-min-max-loop.md
│ ├── js-set-map-lookups.md
│ ├── js-tosorted-immutable.md
│ ├── rendering-activity.md
│ ├── rendering-animate-svg-wrapper.md
│ ├── rendering-conditional-render.md
│ ├── rendering-content-visibility.md
│ ├── rendering-hoist-jsx.md
│ ├── rendering-hydration-no-flicker.md
│ ├── rendering-hydration-suppress-warning.md
│ ├── rendering-resource-hints.md
│ ├── rendering-script-defer-async.md
│ ├── rendering-svg-precision.md
│ ├── rendering-usetransition-loading.md
│ ├── rerender-defer-reads.md
│ ├── rerender-dependencies.md
│ ├── rerender-derived-state-no-effect.md
│ ├── rerender-derived-state.md
│ ├── rerender-functional-setstate.md
│ ├── rerender-lazy-state-init.md
│ ├── rerender-memo-with-default-value.md
│ ├── rerender-memo.md
│ ├── rerender-move-effect-to-event.md
│ ├── rerender-no-inline-components.md
│ ├── rerender-simple-expression-in-memo.md
│ ├── rerender-split-combined-hooks.md
│ ├── rerender-transitions.md
│ ├── rerender-use-deferred-value.md
│ ├── rerender-use-ref-transient-values.md
│ ├── server-after-nonblocking.md
│ ├── server-auth-actions.md
│ ├── server-cache-lru.md
│ ├── server-cache-react.md
│ ├── server-dedup-props.md
│ ├── server-hoist-static-io.md
│ ├── server-parallel-fetching.md
│ └── server-serialization.md
├── react-native-skills/
│ ├── AGENTS.md
│ ├── README.md
│ ├── SKILL.md
│ ├── metadata.json
│ └── rules/
│ ├── _sections.md
│ ├── _template.md
│ ├── animation-derived-value.md
│ ├── animation-gesture-detector-press.md
│ ├── animation-gpu-properties.md
│ ├── design-system-compound-components.md
│ ├── fonts-config-plugin.md
│ ├── imports-design-system-folder.md
│ ├── js-hoist-intl.md
│ ├── list-performance-callbacks.md
│ ├── list-performance-function-references.md
│ ├── list-performance-images.md
│ ├── list-performance-inline-objects.md
│ ├── list-performance-item-expensive.md
│ ├── list-performance-item-memo.md
│ ├── list-performance-item-types.md
│ ├── list-performance-virtualize.md
│ ├── monorepo-native-deps-in-app.md
│ ├── monorepo-single-dependency-versions.md
│ ├── navigation-native-navigators.md
│ ├── react-compiler-destructure-functions.md
│ ├── react-compiler-reanimated-shared-values.md
│ ├── react-state-dispatcher.md
│ ├── react-state-fallback.md
│ ├── react-state-minimize.md
│ ├── rendering-no-falsy-and.md
│ ├── rendering-text-in-text-component.md
│ ├── scroll-position-no-state.md
│ ├── state-ground-truth.md
│ ├── ui-expo-image.md
│ ├── ui-image-gallery.md
│ ├── ui-measure-views.md
│ ├── ui-menus.md
│ ├── ui-native-modals.md
│ ├── ui-pressable.md
│ ├── ui-safe-area-scroll.md
│ ├── ui-scrollview-content-inset.md
│ └── ui-styling.md
├── vercel-cli-with-tokens/
│ └── SKILL.md
└── web-design-guidelines/
└── SKILL.md
SYMBOL INDEX (32 symbols across 7 files)
FILE: packages/react-best-practices-build/src/build.ts
function incrementVersion (line 22) | function incrementVersion(version: string): string {
function generateMarkdown (line 32) | function generateMarkdown(
function buildSkill (line 135) | async function buildSkill(skillConfig: SkillConfig) {
function build (line 290) | async function build() {
FILE: packages/react-best-practices-build/src/config.ts
constant SKILLS_DIR (line 11) | const SKILLS_DIR = join(__dirname, '../../..', 'skills')
constant BUILD_DIR (line 12) | const BUILD_DIR = join(__dirname, '..')
type SkillConfig (line 15) | interface SkillConfig {
constant SKILLS (line 26) | const SKILLS: Record<string, SkillConfig> = {
constant DEFAULT_SKILL (line 89) | const DEFAULT_SKILL = 'react-best-practices'
constant SKILL_DIR (line 92) | const SKILL_DIR = SKILLS[DEFAULT_SKILL].skillDir
constant RULES_DIR (line 93) | const RULES_DIR = SKILLS[DEFAULT_SKILL].rulesDir
constant METADATA_FILE (line 94) | const METADATA_FILE = SKILLS[DEFAULT_SKILL].metadataFile
constant OUTPUT_FILE (line 95) | const OUTPUT_FILE = SKILLS[DEFAULT_SKILL].outputFile
constant TEST_CASES_FILE (line 98) | const TEST_CASES_FILE = join(BUILD_DIR, 'test-cases.json')
FILE: packages/react-best-practices-build/src/extract-tests.ts
function extractTestCases (line 15) | function extractTestCases(rule: Rule): TestCase[] {
function extractTests (line 43) | async function extractTests() {
FILE: packages/react-best-practices-build/src/migrate.ts
constant RPG_FILE (line 12) | const RPG_FILE = join(SKILL_DIR, 'RPG.md')
function parseSectionHeading (line 17) | function parseSectionHeading(line: string): { number: number; title: str...
function parseRuleHeading (line 31) | function parseRuleHeading(line: string): { section: number; subsection: ...
function extractImpact (line 46) | function extractImpact(line: string): { impact: string; description?: st...
function migrate (line 57) | async function migrate() {
FILE: packages/react-best-practices-build/src/parser.ts
type RuleFile (line 9) | interface RuleFile {
function parseRuleFile (line 18) | async function parseRuleFile(
FILE: packages/react-best-practices-build/src/types.ts
type ImpactLevel (line 5) | type ImpactLevel = 'CRITICAL' | 'HIGH' | 'MEDIUM-HIGH' | 'MEDIUM' | 'LOW...
type CodeExample (line 7) | interface CodeExample {
type Rule (line 15) | interface Rule {
type Section (line 28) | interface Section {
type GuidelinesDocument (line 37) | interface GuidelinesDocument {
type TestCase (line 46) | interface TestCase {
FILE: packages/react-best-practices-build/src/validate.ts
type ValidationError (line 12) | interface ValidationError {
function validateRule (line 21) | function validateRule(rule: Rule, file: string): ValidationError[] {
function validate (line 71) | async function validate() {
Condensed preview — 146 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (592K chars).
[
{
"path": ".github/workflows/react-best-practices-ci.yml",
"chars": 822,
"preview": "name: React Best Practices CI\n\non:\n push:\n branches: [main]\n paths:\n - 'skills/react-best-practices/**'\n "
},
{
"path": ".gitignore",
"chars": 30,
"preview": ".DS_Store\n.vercel\n.env*.local\n"
},
{
"path": "AGENTS.md",
"chars": 3269,
"preview": "# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code"
},
{
"path": "README.md",
"chars": 4586,
"preview": "# Agent Skills\n\nA collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend ag"
},
{
"path": "packages/react-best-practices-build/.gitignore",
"chars": 14,
"preview": "node_modules/\n"
},
{
"path": "packages/react-best-practices-build/package.json",
"chars": 931,
"preview": "{\n \"name\": \"react-best-practices-build\",\n \"version\": \"1.0.0\",\n \"description\": \"Build tooling for React Best Practices"
},
{
"path": "packages/react-best-practices-build/src/build.ts",
"chars": 9962,
"preview": "#!/usr/bin/env node\n/**\n * Build script to compile individual rule files into AGENTS.md\n */\n\nimport { readdir, readFile,"
},
{
"path": "packages/react-best-practices-build/src/config.ts",
"chars": 2902,
"preview": "/**\n * Configuration for the build tooling\n */\n\nimport { join, dirname } from 'path'\nimport { fileURLToPath } from 'url'"
},
{
"path": "packages/react-best-practices-build/src/extract-tests.ts",
"chars": 2453,
"preview": "#!/usr/bin/env node\n/**\n * Extract test cases from rules for LLM evaluation\n */\n\nimport { readdir, writeFile } from 'fs/"
},
{
"path": "packages/react-best-practices-build/src/migrate.ts",
"chars": 5545,
"preview": "#!/usr/bin/env node\n/**\n * Migration script to split RPG.md into individual rule files\n * This is a one-time script to h"
},
{
"path": "packages/react-best-practices-build/src/parser.ts",
"chars": 7850,
"preview": "/**\n * Parser for rule markdown files\n */\n\nimport { readFile } from 'fs/promises'\nimport { basename } from 'path'\nimport"
},
{
"path": "packages/react-best-practices-build/src/types.ts",
"chars": 1336,
"preview": "/**\n * Type definitions for React Performance Guidelines rules\n */\n\nexport type ImpactLevel = 'CRITICAL' | 'HIGH' | 'MED"
},
{
"path": "packages/react-best-practices-build/src/validate.ts",
"chars": 3533,
"preview": "#!/usr/bin/env node\n/**\n * Validate rule files follow the correct structure\n */\n\nimport { readdir } from 'fs/promises'\ni"
},
{
"path": "packages/react-best-practices-build/test-cases.json",
"chars": 58275,
"preview": "[\n {\n \"ruleId\": \"\",\n \"ruleTitle\": \"Store Event Handlers in Refs\",\n \"type\": \"bad\",\n \"code\": \"function useWin"
},
{
"path": "packages/react-best-practices-build/tsconfig.json",
"chars": 399,
"preview": "{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"ESNext\",\n \"lib\": [\"ES2022\"],\n \"moduleResolution\": "
},
{
"path": "skills/composition-patterns/AGENTS.md",
"chars": 22604,
"preview": "# React Composition Patterns\n\n**Version 1.0.0** \nEngineering \nJanuary 2026\n\n> **Note:** \n> This document is mainly fo"
},
{
"path": "skills/composition-patterns/README.md",
"chars": 2132,
"preview": "# React Composition Patterns\n\nA structured repository for React composition patterns that scale. These\npatterns help avo"
},
{
"path": "skills/composition-patterns/SKILL.md",
"chars": 2882,
"preview": "---\nname: vercel-composition-patterns\ndescription:\n React composition patterns that scale. Use when refactoring compone"
},
{
"path": "skills/composition-patterns/metadata.json",
"chars": 530,
"preview": "{\n \"version\": \"1.0.0\",\n \"organization\": \"Engineering\",\n \"date\": \"January 2026\",\n \"abstract\": \"Composition patterns f"
},
{
"path": "skills/composition-patterns/rules/_sections.md",
"chars": 829,
"preview": "# Sections\n\nThis file defines all sections, their ordering, impact levels, and descriptions.\nThe section ID (in parenthe"
},
{
"path": "skills/composition-patterns/rules/_template.md",
"chars": 329,
"preview": "---\ntitle: Rule Title Here\nimpact: MEDIUM\nimpactDescription: brief description of impact\ntags: composition, components\n-"
},
{
"path": "skills/composition-patterns/rules/architecture-avoid-boolean-props.md",
"chars": 2267,
"preview": "---\ntitle: Avoid Boolean Prop Proliferation\nimpact: CRITICAL\nimpactDescription: prevents unmaintainable component varian"
},
{
"path": "skills/composition-patterns/rules/architecture-compound-components.md",
"chars": 2600,
"preview": "---\ntitle: Use Compound Components\nimpact: HIGH\nimpactDescription: enables flexible composition without prop drilling\nta"
},
{
"path": "skills/composition-patterns/rules/patterns-children-over-render-props.md",
"chars": 1886,
"preview": "---\ntitle: Prefer Composing Children Over Render Props\nimpact: MEDIUM\nimpactDescription: cleaner composition, better rea"
},
{
"path": "skills/composition-patterns/rules/patterns-explicit-variants.md",
"chars": 2395,
"preview": "---\ntitle: Create Explicit Component Variants\nimpact: MEDIUM\nimpactDescription: self-documenting code, no hidden conditi"
},
{
"path": "skills/composition-patterns/rules/react19-no-forwardref.md",
"chars": 949,
"preview": "---\ntitle: React 19 API Changes\nimpact: MEDIUM\nimpactDescription: cleaner component definitions and context usage\ntags: "
},
{
"path": "skills/composition-patterns/rules/state-context-interface.md",
"chars": 4970,
"preview": "---\ntitle: Define Generic Context Interfaces for Dependency Injection\nimpact: HIGH\nimpactDescription: enables dependency"
},
{
"path": "skills/composition-patterns/rules/state-decouple-implementation.md",
"chars": 2697,
"preview": "---\ntitle: Decouple State Management from UI\nimpact: MEDIUM\nimpactDescription: enables swapping state implementations wi"
},
{
"path": "skills/composition-patterns/rules/state-lift-state.md",
"chars": 3219,
"preview": "---\ntitle: Lift State into Provider Components\nimpact: HIGH\nimpactDescription: enables state sharing outside component b"
},
{
"path": "skills/deploy-to-vercel/SKILL.md",
"chars": 11744,
"preview": "---\nname: deploy-to-vercel\ndescription: Deploy applications and websites to Vercel. Use when the user requests deploymen"
},
{
"path": "skills/deploy-to-vercel/resources/deploy-codex.sh",
"chars": 8855,
"preview": "#!/bin/bash\n\n# Vercel Deployment Script for Codex (via claimable deploy endpoint)\n# Usage: ./deploy-codex.sh [project-pa"
},
{
"path": "skills/deploy-to-vercel/resources/deploy.sh",
"chars": 8841,
"preview": "#!/bin/bash\n\n# Vercel Deployment Script (via claimable deploy endpoint)\n# Usage: ./deploy.sh [project-path]\n# Returns: J"
},
{
"path": "skills/react-best-practices/AGENTS.md",
"chars": 94449,
"preview": "# React Best Practices\n\n**Version 1.0.0** \nVercel Engineering \nJanuary 2026\n\n> **Note:** \n> This document is mainly f"
},
{
"path": "skills/react-best-practices/README.md",
"chars": 3360,
"preview": "# React Best Practices\n\nA structured repository for creating and maintaining React Best Practices optimized for agents a"
},
{
"path": "skills/react-best-practices/SKILL.md",
"chars": 6691,
"preview": "---\nname: vercel-react-best-practices\ndescription: React and Next.js performance optimization guidelines from Vercel Eng"
},
{
"path": "skills/react-best-practices/metadata.json",
"chars": 921,
"preview": "{\n \"version\": \"1.0.0\",\n \"organization\": \"Vercel Engineering\",\n \"date\": \"January 2026\",\n \"abstract\": \"Comprehensive p"
},
{
"path": "skills/react-best-practices/rules/_sections.md",
"chars": 1554,
"preview": "# Sections\n\nThis file defines all sections, their ordering, impact levels, and descriptions.\nThe section ID (in parenthe"
},
{
"path": "skills/react-best-practices/rules/_template.md",
"chars": 631,
"preview": "---\ntitle: Rule Title Here\nimpact: MEDIUM\nimpactDescription: Optional description of impact (e.g., \"20-50% improvement\")"
},
{
"path": "skills/react-best-practices/rules/advanced-event-handler-refs.md",
"chars": 1483,
"preview": "---\ntitle: Store Event Handlers in Refs\nimpact: LOW\nimpactDescription: stable subscriptions\ntags: advanced, hooks, refs,"
},
{
"path": "skills/react-best-practices/rules/advanced-init-once.md",
"chars": 958,
"preview": "---\ntitle: Initialize App Once, Not Per Mount\nimpact: LOW-MEDIUM\nimpactDescription: avoids duplicate init in development"
},
{
"path": "skills/react-best-practices/rules/advanced-use-latest.md",
"chars": 1072,
"preview": "---\ntitle: useEffectEvent for Stable Callback Refs\nimpact: LOW\nimpactDescription: prevents effect re-runs\ntags: advanced"
},
{
"path": "skills/react-best-practices/rules/async-api-routes.md",
"chars": 1124,
"preview": "---\ntitle: Prevent Waterfall Chains in API Routes\nimpact: CRITICAL\nimpactDescription: 2-10× improvement\ntags: api-routes"
},
{
"path": "skills/react-best-practices/rules/async-defer-await.md",
"chars": 2028,
"preview": "---\ntitle: Defer Await Until Needed\nimpact: HIGH\nimpactDescription: avoids blocking unused code paths\ntags: async, await"
},
{
"path": "skills/react-best-practices/rules/async-dependencies.md",
"chars": 1292,
"preview": "---\ntitle: Dependency-Based Parallelization\nimpact: CRITICAL\nimpactDescription: 2-10× improvement\ntags: async, paralleli"
},
{
"path": "skills/react-best-practices/rules/async-parallel.md",
"chars": 653,
"preview": "---\ntitle: Promise.all() for Independent Operations\nimpact: CRITICAL\nimpactDescription: 2-10× improvement\ntags: async, p"
},
{
"path": "skills/react-best-practices/rules/async-suspense-boundaries.md",
"chars": 2508,
"preview": "---\ntitle: Strategic Suspense Boundaries\nimpact: HIGH\nimpactDescription: faster initial paint\ntags: async, suspense, str"
},
{
"path": "skills/react-best-practices/rules/bundle-barrel-imports.md",
"chars": 2370,
"preview": "---\ntitle: Avoid Barrel File Imports\nimpact: CRITICAL\nimpactDescription: 200-800ms import cost, slow builds\ntags: bundle"
},
{
"path": "skills/react-best-practices/rules/bundle-conditional.md",
"chars": 949,
"preview": "---\ntitle: Conditional Module Loading\nimpact: HIGH\nimpactDescription: loads large data only when needed\ntags: bundle, co"
},
{
"path": "skills/react-best-practices/rules/bundle-defer-third-party.md",
"chars": 920,
"preview": "---\ntitle: Defer Non-Critical Third-Party Libraries\nimpact: MEDIUM\nimpactDescription: loads after hydration\ntags: bundle"
},
{
"path": "skills/react-best-practices/rules/bundle-dynamic-imports.md",
"chars": 791,
"preview": "---\ntitle: Dynamic Imports for Heavy Components\nimpact: CRITICAL\nimpactDescription: directly affects TTI and LCP\ntags: b"
},
{
"path": "skills/react-best-practices/rules/bundle-preload.md",
"chars": 1149,
"preview": "---\ntitle: Preload Based on User Intent\nimpact: MEDIUM\nimpactDescription: reduces perceived latency\ntags: bundle, preloa"
},
{
"path": "skills/react-best-practices/rules/client-event-listeners.md",
"chars": 1969,
"preview": "---\ntitle: Deduplicate Global Event Listeners\nimpact: LOW\nimpactDescription: single listener for N components\ntags: clie"
},
{
"path": "skills/react-best-practices/rules/client-localstorage-schema.md",
"chars": 1950,
"preview": "---\ntitle: Version and Minimize localStorage Data\nimpact: MEDIUM\nimpactDescription: prevents schema conflicts, reduces s"
},
{
"path": "skills/react-best-practices/rules/client-passive-event-listeners.md",
"chars": 1644,
"preview": "---\ntitle: Use Passive Event Listeners for Scrolling Performance\nimpact: MEDIUM\nimpactDescription: eliminates scroll del"
},
{
"path": "skills/react-best-practices/rules/client-swr-dedup.md",
"chars": 1159,
"preview": "---\ntitle: Use SWR for Automatic Deduplication\nimpact: MEDIUM-HIGH\nimpactDescription: automatic deduplication\ntags: clie"
},
{
"path": "skills/react-best-practices/rules/js-batch-dom-css.md",
"chars": 3266,
"preview": "---\ntitle: Avoid Layout Thrashing\nimpact: MEDIUM\nimpactDescription: prevents forced synchronous layouts and reduces perf"
},
{
"path": "skills/react-best-practices/rules/js-cache-function-results.md",
"chars": 1949,
"preview": "---\ntitle: Cache Repeated Function Calls\nimpact: MEDIUM\nimpactDescription: avoid redundant computation\ntags: javascript,"
},
{
"path": "skills/react-best-practices/rules/js-cache-property-access.md",
"chars": 531,
"preview": "---\ntitle: Cache Property Access in Loops\nimpact: LOW-MEDIUM\nimpactDescription: reduces lookups\ntags: javascript, loops,"
},
{
"path": "skills/react-best-practices/rules/js-cache-storage.md",
"chars": 1651,
"preview": "---\ntitle: Cache Storage API Calls\nimpact: LOW-MEDIUM\nimpactDescription: reduces expensive I/O\ntags: javascript, localSt"
},
{
"path": "skills/react-best-practices/rules/js-combine-iterations.md",
"chars": 753,
"preview": "---\ntitle: Combine Multiple Array Iterations\nimpact: LOW-MEDIUM\nimpactDescription: reduces iterations\ntags: javascript, "
},
{
"path": "skills/react-best-practices/rules/js-early-exit.md",
"chars": 1133,
"preview": "---\ntitle: Early Return from Functions\nimpact: LOW-MEDIUM\nimpactDescription: avoids unnecessary computation\ntags: javasc"
},
{
"path": "skills/react-best-practices/rules/js-flatmap-filter.md",
"chars": 1411,
"preview": "---\ntitle: Use flatMap to Map and Filter in One Pass\nimpact: LOW-MEDIUM\nimpactDescription: eliminates intermediate array"
},
{
"path": "skills/react-best-practices/rules/js-hoist-regexp.md",
"chars": 1028,
"preview": "---\ntitle: Hoist RegExp Creation\nimpact: LOW-MEDIUM\nimpactDescription: avoids recreation\ntags: javascript, regexp, optim"
},
{
"path": "skills/react-best-practices/rules/js-index-maps.md",
"chars": 834,
"preview": "---\ntitle: Build Index Maps for Repeated Lookups\nimpact: LOW-MEDIUM\nimpactDescription: 1M ops to 2K ops\ntags: javascript"
},
{
"path": "skills/react-best-practices/rules/js-length-check-first.md",
"chars": 1747,
"preview": "---\ntitle: Early Length Check for Array Comparisons\nimpact: MEDIUM-HIGH\nimpactDescription: avoids expensive operations w"
},
{
"path": "skills/react-best-practices/rules/js-min-max-loop.md",
"chars": 2290,
"preview": "---\ntitle: Use Loop for Min/Max Instead of Sort\nimpact: LOW\nimpactDescription: O(n) instead of O(n log n)\ntags: javascri"
},
{
"path": "skills/react-best-practices/rules/js-set-map-lookups.md",
"chars": 532,
"preview": "---\ntitle: Use Set/Map for O(1) Lookups\nimpact: LOW-MEDIUM\nimpactDescription: O(n) to O(1)\ntags: javascript, set, map, d"
},
{
"path": "skills/react-best-practices/rules/js-tosorted-immutable.md",
"chars": 1782,
"preview": "---\ntitle: Use toSorted() Instead of sort() for Immutability\nimpact: MEDIUM-HIGH\nimpactDescription: prevents mutation bu"
},
{
"path": "skills/react-best-practices/rules/rendering-activity.md",
"chars": 564,
"preview": "---\ntitle: Use Activity Component for Show/Hide\nimpact: MEDIUM\nimpactDescription: preserves state/DOM\ntags: rendering, a"
},
{
"path": "skills/react-best-practices/rules/rendering-animate-svg-wrapper.md",
"chars": 1185,
"preview": "---\ntitle: Animate SVG Wrapper Instead of SVG Element\nimpact: LOW\nimpactDescription: enables hardware acceleration\ntags:"
},
{
"path": "skills/react-best-practices/rules/rendering-conditional-render.md",
"chars": 980,
"preview": "---\ntitle: Use Explicit Conditional Rendering\nimpact: LOW\nimpactDescription: prevents rendering 0 or NaN\ntags: rendering"
},
{
"path": "skills/react-best-practices/rules/rendering-content-visibility.md",
"chars": 814,
"preview": "---\ntitle: CSS content-visibility for Long Lists\nimpact: HIGH\nimpactDescription: faster initial render\ntags: rendering, "
},
{
"path": "skills/react-best-practices/rules/rendering-hoist-jsx.md",
"chars": 1039,
"preview": "---\ntitle: Hoist Static JSX Elements\nimpact: LOW\nimpactDescription: avoids re-creation\ntags: rendering, jsx, static, opt"
},
{
"path": "skills/react-best-practices/rules/rendering-hydration-no-flicker.md",
"chars": 2308,
"preview": "---\ntitle: Prevent Hydration Mismatch Without Flickering\nimpact: MEDIUM\nimpactDescription: avoids visual flicker and hyd"
},
{
"path": "skills/react-best-practices/rules/rendering-hydration-suppress-warning.md",
"chars": 870,
"preview": "---\ntitle: Suppress Expected Hydration Mismatches\nimpact: LOW-MEDIUM\nimpactDescription: avoids noisy hydration warnings "
},
{
"path": "skills/react-best-practices/rules/rendering-resource-hints.md",
"chars": 2549,
"preview": "---\ntitle: Use React DOM Resource Hints\nimpact: HIGH\nimpactDescription: reduces load time for critical resources\ntags: r"
},
{
"path": "skills/react-best-practices/rules/rendering-script-defer-async.md",
"chars": 1868,
"preview": "---\ntitle: Use defer or async on Script Tags\nimpact: HIGH\nimpactDescription: eliminates render-blocking\ntags: rendering,"
},
{
"path": "skills/react-best-practices/rules/rendering-svg-precision.md",
"chars": 588,
"preview": "---\ntitle: Optimize SVG Precision\nimpact: LOW\nimpactDescription: reduces file size\ntags: rendering, svg, optimization, s"
},
{
"path": "skills/react-best-practices/rules/rendering-usetransition-loading.md",
"chars": 2074,
"preview": "---\ntitle: Use useTransition Over Manual Loading States\nimpact: LOW\nimpactDescription: reduces re-renders and improves c"
},
{
"path": "skills/react-best-practices/rules/rerender-defer-reads.md",
"chars": 973,
"preview": "---\ntitle: Defer State Reads to Usage Point\nimpact: MEDIUM\nimpactDescription: avoids unnecessary subscriptions\ntags: rer"
},
{
"path": "skills/react-best-practices/rules/rerender-dependencies.md",
"chars": 824,
"preview": "---\ntitle: Narrow Effect Dependencies\nimpact: LOW\nimpactDescription: minimizes effect re-runs\ntags: rerender, useEffect,"
},
{
"path": "skills/react-best-practices/rules/rerender-derived-state-no-effect.md",
"chars": 1201,
"preview": "---\ntitle: Calculate Derived State During Rendering\nimpact: MEDIUM\nimpactDescription: avoids redundant renders and state"
},
{
"path": "skills/react-best-practices/rules/rerender-derived-state.md",
"chars": 728,
"preview": "---\ntitle: Subscribe to Derived State\nimpact: MEDIUM\nimpactDescription: reduces re-render frequency\ntags: rerender, deri"
},
{
"path": "skills/react-best-practices/rules/rerender-functional-setstate.md",
"chars": 2958,
"preview": "---\ntitle: Use Functional setState Updates\nimpact: MEDIUM\nimpactDescription: prevents stale closures and unnecessary cal"
},
{
"path": "skills/react-best-practices/rules/rerender-lazy-state-init.md",
"chars": 2016,
"preview": "---\ntitle: Use Lazy State Initialization\nimpact: MEDIUM\nimpactDescription: wasted computation on every render\ntags: reac"
},
{
"path": "skills/react-best-practices/rules/rerender-memo-with-default-value.md",
"chars": 1173,
"preview": "---\n\ntitle: Extract Default Non-primitive Parameter Value from Memoized Component to Constant\nimpact: MEDIUM\nimpactDescr"
},
{
"path": "skills/react-best-practices/rules/rerender-memo.md",
"chars": 1148,
"preview": "---\ntitle: Extract to Memoized Components\nimpact: MEDIUM\nimpactDescription: enables early returns\ntags: rerender, memo, "
},
{
"path": "skills/react-best-practices/rules/rerender-move-effect-to-event.md",
"chars": 1268,
"preview": "---\ntitle: Put Interaction Logic in Event Handlers\nimpact: MEDIUM\nimpactDescription: avoids effect re-runs and duplicate"
},
{
"path": "skills/react-best-practices/rules/rerender-no-inline-components.md",
"chars": 2135,
"preview": "---\ntitle: Don't Define Components Inside Components\nimpact: HIGH\nimpactDescription: prevents remount on every render\nta"
},
{
"path": "skills/react-best-practices/rules/rerender-simple-expression-in-memo.md",
"chars": 1018,
"preview": "---\ntitle: Do not wrap a simple expression with a primitive result type in useMemo\nimpact: LOW-MEDIUM\nimpactDescription:"
},
{
"path": "skills/react-best-practices/rules/rerender-split-combined-hooks.md",
"chars": 1844,
"preview": "---\ntitle: Split Combined Hook Computations\nimpact: MEDIUM\nimpactDescription: avoids recomputing independent steps\ntags:"
},
{
"path": "skills/react-best-practices/rules/rerender-transitions.md",
"chars": 1055,
"preview": "---\ntitle: Use Transitions for Non-Urgent Updates\nimpact: MEDIUM\nimpactDescription: maintains UI responsiveness\ntags: re"
},
{
"path": "skills/react-best-practices/rules/rerender-use-deferred-value.md",
"chars": 1846,
"preview": "---\ntitle: Use useDeferredValue for Expensive Derived Renders\nimpact: MEDIUM\nimpactDescription: keeps input responsive d"
},
{
"path": "skills/react-best-practices/rules/rerender-use-ref-transient-values.md",
"chars": 1742,
"preview": "---\ntitle: Use useRef for Transient Values\nimpact: MEDIUM\nimpactDescription: avoids unnecessary re-renders on frequent u"
},
{
"path": "skills/react-best-practices/rules/server-after-nonblocking.md",
"chars": 2012,
"preview": "---\ntitle: Use after() for Non-Blocking Operations\nimpact: MEDIUM\nimpactDescription: faster response times\ntags: server,"
},
{
"path": "skills/react-best-practices/rules/server-auth-actions.md",
"chars": 2647,
"preview": "---\ntitle: Authenticate Server Actions Like API Routes\nimpact: CRITICAL\nimpactDescription: prevents unauthorized access "
},
{
"path": "skills/react-best-practices/rules/server-cache-lru.md",
"chars": 1353,
"preview": "---\ntitle: Cross-Request LRU Caching\nimpact: HIGH\nimpactDescription: caches across requests\ntags: server, cache, lru, cr"
},
{
"path": "skills/react-best-practices/rules/server-cache-react.md",
"chars": 2228,
"preview": "---\ntitle: Per-Request Deduplication with React.cache()\nimpact: MEDIUM\nimpactDescription: deduplicates within request\nta"
},
{
"path": "skills/react-best-practices/rules/server-dedup-props.md",
"chars": 2053,
"preview": "---\ntitle: Avoid Duplicate Serialization in RSC Props\nimpact: LOW\nimpactDescription: reduces network payload by avoiding"
},
{
"path": "skills/react-best-practices/rules/server-hoist-static-io.md",
"chars": 4393,
"preview": "---\ntitle: Hoist Static I/O to Module Level\nimpact: HIGH\nimpactDescription: avoids repeated file/network I/O per request"
},
{
"path": "skills/react-best-practices/rules/server-parallel-fetching.md",
"chars": 1554,
"preview": "---\ntitle: Parallel Data Fetching with Component Composition\nimpact: CRITICAL\nimpactDescription: eliminates server-side "
},
{
"path": "skills/react-best-practices/rules/server-serialization.md",
"chars": 996,
"preview": "---\ntitle: Minimize Serialization at RSC Boundaries\nimpact: HIGH\nimpactDescription: reduces data transfer size\ntags: ser"
},
{
"path": "skills/react-native-skills/AGENTS.md",
"chars": 73669,
"preview": "# React Native Skills\n\n**Version 1.0.0** \nEngineering \nJanuary 2026\n\n> **Note:** \n> This document is mainly for agent"
},
{
"path": "skills/react-native-skills/README.md",
"chars": 5064,
"preview": "# React Native Guidelines\n\nA structured repository for creating and maintaining React Native Best Practices\noptimized fo"
},
{
"path": "skills/react-native-skills/SKILL.md",
"chars": 4439,
"preview": "---\nname: vercel-react-native-skills\ndescription:\n React Native and Expo best practices for building performant mobile "
},
{
"path": "skills/react-native-skills/metadata.json",
"chars": 896,
"preview": "{\n \"version\": \"1.0.0\",\n \"organization\": \"Engineering\",\n \"date\": \"January 2026\",\n \"abstract\": \"Comprehensive performa"
},
{
"path": "skills/react-native-skills/rules/_sections.md",
"chars": 2228,
"preview": "# Sections\n\nThis file defines all sections, their ordering, impact levels, and descriptions.\nThe section ID (in parenthe"
},
{
"path": "skills/react-native-skills/rules/_template.md",
"chars": 631,
"preview": "---\ntitle: Rule Title Here\nimpact: MEDIUM\nimpactDescription: Optional description of impact (e.g., \"20-50% improvement\")"
},
{
"path": "skills/react-native-skills/rules/animation-derived-value.md",
"chars": 1373,
"preview": "---\ntitle: Prefer useDerivedValue Over useAnimatedReaction\nimpact: MEDIUM\nimpactDescription: cleaner code, automatic dep"
},
{
"path": "skills/react-native-skills/rules/animation-gesture-detector-press.md",
"chars": 2557,
"preview": "---\ntitle: Use GestureDetector for Animated Press States\nimpact: MEDIUM\nimpactDescription: UI thread animations, smoothe"
},
{
"path": "skills/react-native-skills/rules/animation-gpu-properties.md",
"chars": 2059,
"preview": "---\ntitle: Animate Transform and Opacity Instead of Layout Properties\nimpact: HIGH\nimpactDescription: GPU-accelerated an"
},
{
"path": "skills/react-native-skills/rules/design-system-compound-components.md",
"chars": 1625,
"preview": "---\ntitle: Use Compound Components Over Polymorphic Children\nimpact: MEDIUM\nimpactDescription: flexible composition, cle"
},
{
"path": "skills/react-native-skills/rules/fonts-config-plugin.md",
"chars": 1391,
"preview": "---\ntitle: Load fonts natively at build time\nimpact: LOW\nimpactDescription: fonts available at launch, no async loading\n"
},
{
"path": "skills/react-native-skills/rules/imports-design-system-folder.md",
"chars": 1418,
"preview": "---\ntitle: Import from Design System Folder\nimpact: LOW\nimpactDescription: enables global changes and easy refactoring\nt"
},
{
"path": "skills/react-native-skills/rules/js-hoist-intl.md",
"chars": 1643,
"preview": "---\ntitle: Hoist Intl Formatter Creation\nimpact: LOW-MEDIUM\nimpactDescription: avoids expensive object recreation\ntags: "
},
{
"path": "skills/react-native-skills/rules/list-performance-callbacks.md",
"chars": 1059,
"preview": "---\ntitle: Hoist callbacks to the root of lists\nimpact: MEDIUM\nimpactDescription: Fewer re-renders and faster lists\ntags"
},
{
"path": "skills/react-native-skills/rules/list-performance-function-references.md",
"chars": 4129,
"preview": "---\ntitle: Optimize List Performance with Stable Object References\nimpact: CRITICAL\nimpactDescription: virtualization re"
},
{
"path": "skills/react-native-skills/rules/list-performance-images.md",
"chars": 1417,
"preview": "---\ntitle: Use Compressed Images in Lists\nimpact: HIGH\nimpactDescription: faster load times, less memory\ntags: lists, im"
},
{
"path": "skills/react-native-skills/rules/list-performance-inline-objects.md",
"chars": 2308,
"preview": "---\ntitle: Avoid Inline Objects in renderItem\nimpact: HIGH\nimpactDescription: prevents unnecessary re-renders of memoize"
},
{
"path": "skills/react-native-skills/rules/list-performance-item-expensive.md",
"chars": 2464,
"preview": "---\ntitle: Keep List Items Lightweight\nimpact: HIGH\nimpactDescription: reduces render time for visible items during scro"
},
{
"path": "skills/react-native-skills/rules/list-performance-item-memo.md",
"chars": 2250,
"preview": "---\ntitle: Pass Primitives to List Items for Memoization\nimpact: HIGH\nimpactDescription: enables effective memo() compar"
},
{
"path": "skills/react-native-skills/rules/list-performance-item-types.md",
"chars": 2749,
"preview": "---\ntitle: Use Item Types for Heterogeneous Lists\nimpact: HIGH\nimpactDescription: efficient recycling, less layout thras"
},
{
"path": "skills/react-native-skills/rules/list-performance-virtualize.md",
"chars": 1738,
"preview": "---\ntitle: Use a List Virtualizer for Any List\nimpact: HIGH\nimpactDescription: reduced memory, faster mounts\ntags: lists"
},
{
"path": "skills/react-native-skills/rules/monorepo-native-deps-in-app.md",
"chars": 1087,
"preview": "---\ntitle: Install Native Dependencies in App Directory\nimpact: CRITICAL\nimpactDescription: required for autolinking to "
},
{
"path": "skills/react-native-skills/rules/monorepo-single-dependency-versions.md",
"chars": 1351,
"preview": "---\ntitle: Use Single Dependency Versions Across Monorepo\nimpact: MEDIUM\nimpactDescription: avoids duplicate bundles, ve"
},
{
"path": "skills/react-native-skills/rules/navigation-native-navigators.md",
"chars": 4941,
"preview": "---\ntitle: Use Native Navigators for Navigation\nimpact: HIGH\nimpactDescription: native performance, platform-appropriate"
},
{
"path": "skills/react-native-skills/rules/react-compiler-destructure-functions.md",
"chars": 1274,
"preview": "---\ntitle: Destructure Functions Early in Render (React Compiler)\nimpact: HIGH\nimpactDescription: stable references, few"
},
{
"path": "skills/react-native-skills/rules/react-compiler-reanimated-shared-values.md",
"chars": 1266,
"preview": "---\ntitle: Use .get() and .set() for Reanimated Shared Values (not .value)\nimpact: LOW\nimpactDescription: required for R"
},
{
"path": "skills/react-native-skills/rules/react-state-dispatcher.md",
"chars": 2255,
"preview": "---\ntitle: useState Dispatch updaters for State That Depends on Current Value\nimpact: MEDIUM\nimpactDescription: avoids s"
},
{
"path": "skills/react-native-skills/rules/react-state-fallback.md",
"chars": 1733,
"preview": "---\ntitle: Use fallback state instead of initialState\nimpact: MEDIUM\nimpactDescription: reactive fallbacks without synci"
},
{
"path": "skills/react-native-skills/rules/react-state-minimize.md",
"chars": 1740,
"preview": "---\ntitle: Minimize State Variables and Derive Values\nimpact: MEDIUM\nimpactDescription: fewer re-renders, less state dri"
},
{
"path": "skills/react-native-skills/rules/rendering-no-falsy-and.md",
"chars": 1808,
"preview": "---\ntitle: Never Use && with Potentially Falsy Values\nimpact: CRITICAL\nimpactDescription: prevents production crash\ntags"
},
{
"path": "skills/react-native-skills/rules/rendering-text-in-text-component.md",
"chars": 697,
"preview": "---\ntitle: Wrap Strings in Text Components\nimpact: CRITICAL\nimpactDescription: prevents runtime crash\ntags: rendering, t"
},
{
"path": "skills/react-native-skills/rules/scroll-position-no-state.md",
"chars": 1934,
"preview": "---\ntitle: Never Track Scroll Position in useState\nimpact: HIGH\nimpactDescription: prevents render thrashing during scro"
},
{
"path": "skills/react-native-skills/rules/state-ground-truth.md",
"chars": 2160,
"preview": "---\ntitle: State Must Represent Ground Truth\nimpact: HIGH\nimpactDescription: cleaner logic, easier debugging, single sou"
},
{
"path": "skills/react-native-skills/rules/ui-expo-image.md",
"chars": 1636,
"preview": "---\ntitle: Use expo-image for Optimized Images\nimpact: HIGH\nimpactDescription: memory efficiency, caching, blurhash plac"
},
{
"path": "skills/react-native-skills/rules/ui-image-gallery.md",
"chars": 2546,
"preview": "---\ntitle: Use Galeria for Image Galleries and Lightbox\nimpact: MEDIUM\nimpactDescription:\n native shared element transi"
},
{
"path": "skills/react-native-skills/rules/ui-measure-views.md",
"chars": 2230,
"preview": "---\ntitle: Measuring View Dimensions\nimpact: MEDIUM\nimpactDescription: synchronous measurement, avoid unnecessary re-ren"
},
{
"path": "skills/react-native-skills/rules/ui-menus.md",
"chars": 4598,
"preview": "---\ntitle: Use Native Menus for Dropdowns and Context Menus\nimpact: HIGH\nimpactDescription: native accessibility, platfo"
},
{
"path": "skills/react-native-skills/rules/ui-native-modals.md",
"chars": 1859,
"preview": "---\ntitle: Use Native Modals Over JS-Based Bottom Sheets\nimpact: HIGH\nimpactDescription: native performance, gestures, a"
},
{
"path": "skills/react-native-skills/rules/ui-pressable.md",
"chars": 1534,
"preview": "---\ntitle: Use Pressable Instead of Touchable Components\nimpact: LOW\nimpactDescription: modern API, more flexible\ntags: "
},
{
"path": "skills/react-native-skills/rules/ui-safe-area-scroll.md",
"chars": 1579,
"preview": "---\ntitle: Use contentInsetAdjustmentBehavior for Safe Areas\nimpact: MEDIUM\nimpactDescription: native safe area handling"
},
{
"path": "skills/react-native-skills/rules/ui-scrollview-content-inset.md",
"chars": 1315,
"preview": "---\ntitle: Use contentInset for Dynamic ScrollView Spacing\nimpact: LOW\nimpactDescription: smoother updates, no layout re"
},
{
"path": "skills/react-native-skills/rules/ui-styling.md",
"chars": 2192,
"preview": "---\ntitle: Modern React Native Styling Patterns\nimpact: MEDIUM\nimpactDescription: consistent design, smoother borders, c"
},
{
"path": "skills/vercel-cli-with-tokens/SKILL.md",
"chars": 8804,
"preview": "---\nname: vercel-cli-with-tokens\ndescription: Deploy and manage projects on Vercel using token-based authentication. Use"
},
{
"path": "skills/web-design-guidelines/SKILL.md",
"chars": 1231,
"preview": "---\nname: web-design-guidelines\ndescription: Review UI code for Web Interface Guidelines compliance. Use when asked to \""
}
]
About this extraction
This page contains the full source code of the vercel-labs/agent-skills GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 146 files (542.0 KB), approximately 142.9k tokens, and a symbol index with 32 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.