React Best Practices
shapeshift/web
Comprehensive React and Next.js performance optimization guide with 40+ rules for eliminating waterfalls, optimizing bundles, and improving rendering.
Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring…
Install React Refactor
$ npx skills add pproenca/dot-skills --skill react-refactor -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install pproenca/dot-skills react-refactor --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.experimental/react-refactor .claude/skills/react-refactor && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "react-refactor" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/react-refactor into .claude/skills/react-refactor/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "react-refactor", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/react-refactorType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add pproenca/dot-skills --skill react-refactor -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install pproenca/dot-skills react-refactor --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/.experimental/react-refactor .agents/skills/react-refactor && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "react-refactor" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/react-refactor into .agents/skills/react-refactor/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "react-refactor", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pproenca/dot-skills --skill react-refactor -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install pproenca/dot-skills react-refactor --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/.experimental/react-refactor .cursor/skills/react-refactor && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "react-refactor" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/react-refactor into .cursor/skills/react-refactor/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "react-refactor", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/pproenca/dot-skills.git --path skills/.experimental/react-refactor--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add pproenca/dot-skills --skill react-refactor -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install pproenca/dot-skills react-refactor --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/.experimental/react-refactor .gemini/skills/react-refactor && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "react-refactor" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/react-refactor into .gemini/skills/react-refactor/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "react-refactor", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install pproenca/dot-skills react-refactorInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add pproenca/dot-skills --skill react-refactor -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/.experimental/react-refactor .github/skills/react-refactor && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "react-refactor" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/react-refactor into .github/skills/react-refactor/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "react-refactor", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pproenca/dot-skills --skill react-refactor -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install pproenca/dot-skills react-refactor --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/.experimental/react-refactor .opencode/skills/react-refactor && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "react-refactor" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/react-refactor into .opencode/skills/react-refactor/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "react-refactor", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
react-refactor- GitHub stars
- 214
- Token cost
- ~2.3k tokens
- SKILL.md length
- 796 words
- Files
- 46 (incl. references, assets)
- Skills in repo
- 182
- Repo updated
- First seen
- Licence
- MIT
At a glance
Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring…
- Works in 7 steps: Component Architecture — CRITICAL → State Architecture — CRITICAL → Hook Patterns — HIGH → …
- Refactoring React codebases
- SKILL.md covers When to Apply, Rule Categories, Quick Reference and Table of Contents, plus 2 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
React Refactor is an agent skill from pproenca/dot-skills. Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring safety. Use when refactoring React codebases, reviewing PRs for architectural issues, decomposing oversized components, or improving module boundaries. Does NOT cover React 19 API usage (see react skill) or performance optimization (see react-optimise skill).
Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 48 other files, including reference files and assets (for example `AGENTS.md`, `README.md` and `assets/templates/_template.md`).
It sits in Development, covering Refactoring and Performance optimization. It works with React. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.
When your agent uses it
- Refactoring React codebases
- Reviewing PRs for architectural issues
- Decomposing oversized components
- Improving module boundaries
Example prompts
- “/react-refactor”
Workflow steps
7 steps, taken from the first numbered list in SKILL.md.
- Component Architecture — CRITICAL
- State Architecture — CRITICAL
- Hook Patterns — HIGH
- Component Decomposition — HIGH
- Coupling & Cohesion — MEDIUM
- Data & Side Effects — MEDIUM
- Refactoring Safety — LOW-MEDIUM
What it can do on your machine
Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
react.devkentcdodds.comtesting-library.compatterns.dev
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
React Refactor loads about 2.3k tokens when it runs, and up to ~32k if it reads all its reference files. Until then it costs about 118 tokens; SKILL.md has 796 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 796 words, ~2,329 tokens.
Download SKILL.mdSave it as
.claude/skills/react-refactor/SKILL.md (or your agent's skills folder). This skill also uses 45 other files; get the full folder from GitHub.- name
- react-refactor
- description
- Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring safety. Use when refactoring React codebases, reviewing PRs for architectural issues, decomposing oversized components, or improving module boundaries. Does NOT cover React 19 API usage (see react skill) or performance optimization (see react-optimise skill).
React Refactor Best Practices
Architectural refactoring guide for React applications. Contains 40 rules across 7 categories, prioritized by impact from critical (component and state architecture) to incremental (refactoring safety).
When to Apply
- Refactoring existing React codebases or planning large-scale restructuring
- Reviewing PRs for architectural issues and code smells
- Decomposing oversized components into focused units
- Extracting reusable hooks from component logic
- Improving testability of React code
- Reducing coupling between feature modules
Rule Categories
| Category | Impact | Rules | Key Topics |
|---|---|---|---|
| Component Architecture | CRITICAL | 8 | Compound components, headless pattern, composition over props, client boundaries |
| State Architecture | CRITICAL | 7 | Colocation, state machines, URL state, derived values |
| Hook Patterns | HIGH | 6 | Single responsibility, naming, dependency stability, composition |
| Component Decomposition | HIGH | 6 | Scroll test, extraction by change reason, view/logic separation |
| Coupling & Cohesion | MEDIUM | 4 | Dependency injection, circular deps, stable imports, barrel-free |
| Data & Side Effects | MEDIUM | 4 | Server-first fetch, TanStack Query, error boundaries |
| Refactoring Safety | LOW-MEDIUM | 5 | Characterization tests, behavior testing, integration tests |
Quick Reference
Critical patterns — get these right first:
- Use compound components instead of props explosion
- Colocate state with the components that use it
- Use state machines for complex UI workflows
- Separate container logic from presentational components
Common mistakes — avoid these anti-patterns:
- Lifting state to App when only one component reads it
- Using context for rapidly-changing values
- Monolithic hooks that fetch + transform + cache
- Testing implementation details instead of behavior
Table of Contents
- Component Architecture — CRITICAL
- 1.1 Apply Interface Segregation to Component Props — CRITICAL (prevents 30-50% of unnecessary re-renders)
- 1.2 Colocate Files by Feature Instead of Type — CRITICAL (reduces cross-directory navigation by 70%)
- 1.3 Convert Render Props to Custom Hooks — CRITICAL (eliminates 2-4 levels of nesting)
- 1.4 Extract Headless Components for Logic Reuse — CRITICAL (5x more reuse scenarios)
- 1.5 Prefer Composition Over Props Explosion — CRITICAL (reduces prop count by 50-70%)
- 1.6 Separate Container Logic from Presentational Components — CRITICAL (enables independent testing)
- 1.7 Use Compound Components for Implicit State Sharing — CRITICAL (reduces API surface by 60%)
- 1.8 Push Client Boundaries to Leaf Components — HIGH (keeps 60-80% server-rendered)
- State Architecture — CRITICAL
- 2.1 Colocate State with Components That Use It — CRITICAL (reduces prop passing by 60%)
- 2.2 Derive Values Instead of Syncing State — CRITICAL (eliminates double-render cycle)
- 2.3 Lift State Only When Multiple Components Read It — CRITICAL (eliminates unnecessary parent re-renders)
- 2.4 Use Context for Rarely-Changing Values Only — CRITICAL (5-50x fewer re-renders)
- 2.5 Use State Machines for Complex UI Workflows — CRITICAL (reduces valid states from 2^n to N)
- 2.6 Use URL Parameters as State for Shareable Views — CRITICAL (enables deep linking and sharing)
- 2.7 Use useReducer for Multi-Field State Transitions — CRITICAL (eliminates impossible states)
- Hook Patterns — HIGH
- 3.1 Avoid Object and Array Dependencies in Custom Hooks — HIGH (prevents effect re-execution every render)
- 3.2 Compose Hooks Instead of Nesting Them — HIGH (flattens dependency graph)
- 3.3 Extract Logic into Custom Hooks When Behavior Is Nameable — HIGH (40-60% shorter components)
- 3.4 Follow Hook Naming Conventions for Discoverability — HIGH (reduces navigation time by 40%)
- 3.5 Keep Custom Hooks to a Single Responsibility — HIGH (3x easier to test)
- 3.6 Stabilize Hook Dependencies with Refs and Callbacks — HIGH (prevents infinite loops)
- Component Decomposition — HIGH
- 4.1 Apply the Scroll Test to Identify Oversized Components — HIGH (3x faster code review)
- 4.2 Complete Component Extraction Without Half-Measures — HIGH (enables independent testing and reuse)
- 4.3 Extract Components by Independent Change Reasons — HIGH (70% fewer files touched per change)
- 4.4 Extract Pure Functions from Component Bodies — HIGH (10x faster unit tests)
- 4.5 Inline Premature Abstractions Before Re-Extracting — HIGH (40-60% simpler code)
- 4.6 Separate View Layer from Business Logic — HIGH (5x faster test suite)
- Coupling & Cohesion — MEDIUM
- 5.1 Break Circular Dependencies with Intermediate Modules — MEDIUM (eliminates undefined-at-import-time bugs)
- 5.2 Import from Stable Public API Surfaces Only — MEDIUM (enables internal refactoring)
- 5.3 Use Barrel-Free Feature Modules for Clean Dependencies — MEDIUM (200-800ms build reduction)
- 5.4 Use Dependency Injection for External Services — MEDIUM (3x faster test setup)
- Data & Side Effects — MEDIUM
- 6.1 Fetch Data on the Server by Default — MEDIUM (reduces client JS by 30-60%)
- 6.2 Place Error Boundaries at Data Fetch Granularity — MEDIUM (errors isolated to affected section)
- 6.3 Use Context Module Pattern for Action Colocation — MEDIUM (centralizes data mutations)
- 6.4 Use TanStack Query for Client-Side Server State — MEDIUM (eliminates 80% of fetch boilerplate)
- Refactoring Safety — LOW-MEDIUM
- 7.1 Avoid Snapshot Tests for Refactored Components — LOW-MEDIUM (eliminates false test failures)
- 7.2 Extract Pure Functions to Increase Testability — LOW-MEDIUM (10x faster test execution)
- 7.3 Prefer Integration Tests for Component Verification — LOW-MEDIUM (catches 40% more bugs)
- 7.4 Test Component Behavior Not Implementation Details — LOW-MEDIUM (5x fewer test updates)
- 7.5 Write Characterization Tests Before Refactoring — LOW-MEDIUM (catches 90% of unintended changes)
Show full SKILL.md (36 more words)Show less
References
- https://react.dev
- https://react.dev/learn/thinking-in-react
- https://kentcdodds.com/blog/application-state-management-with-react
- https://testing-library.com/docs/guiding-principles
- https://patterns.dev
Related Skills
- For React 19 API best practices, see
reactskill - For application performance optimization, see
react-optimiseskill - For client-side form handling, see
react-hook-formskill
© pproenca, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 45 other files (references, assets) in skills/.experimental/react-refactor of pproenca/dot-skills.
- SKILL.md
- AGENTS.md
- README.md
- assets/templates/_template.md
- metadata.json
- references/_sections.md
- references/arch-composition-over-props.md
- references/arch-compound-components.md
- references/arch-container-presentational.md
- references/arch-feature-colocation.md
- references/arch-headless-pattern.md
- references/arch-interface-segregation.md
- references/arch-push-client-low.md
- references/arch-render-props-to-hooks.md
- references/couple-barrel-free-features.md
- references/couple-break-circular-deps.md
- references/couple-dependency-injection.md
- references/couple-stable-imports.md
- … and 28 more
Open the folder on GitHubat commit cf93c57
Compare with similar skills
React Refactor next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| React Refactor this skillpproenca/dot-skills | 214 | — | ~2.3k | Automated safety check: Pass | MIT | |
| React Best Practicesshapeshift/web | 206 | 1 repos | ~2k | Automated safety check: Pass | MIT | |
| React Performanceaffaan-m/ECC | 274k | 1 repos | ~4.5k | Automated safety check: Pass | MIT | |
| Vercel React Best Practicessanity-io/sanity | 6.4k | 130 repos | ~1.6k | Automated safety check: Pass | MIT | |
| React Best Practicesryokun6/ryos | 1.3k | — | ~2k | Automated safety check: Pass | MIT | |
| Vercel React Best Practicesgambitph/Stackable | 350 | — | ~2k | Automated safety check: Pass | MIT |
Similar skills
React Performance
affaan-m/ECC
React and Next.js performance optimization patterns adapted from Vercel Engineering's React Best Practices (https://github.com/vercel-labs/agent-skills).
- Official
Vercel React Best Practices
sanity-io/sanity
React and Next.js performance optimization guidelines from Vercel Engineering.
React Best Practices
ryokun6/ryos
React performance optimization guidelines from Vercel Engineering (vercel-labs/agent-skills).
Vercel React Best Practices
gambitph/Stackable
React performance optimization guidelines from Vercel Engineering.
React Best Practices
poteto/noodle
React performance optimization guidelines. An agent skill from poteto/noodle.
More from pproenca/dot-skills
All 182 skills in this repoAudio Voice Recovery
pproenca/dot-skills
Audio forensics and voice recovery guidelines for CSI-level audio analysis.
Codemod React Pipeline
pproenca/dot-skills
Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.
Dev Rfc
pproenca/dot-skills
Create well-structured RFCs and technical proposals for software projects.
Dx Harness
pproenca/dot-skills
Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.
Language Spec Author
pproenca/dot-skills
Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…
Python Pep Author
pproenca/dot-skills
Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…
Related
Works with
Categories
Questions about React Refactor
What does React Refactor do?
Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring…. React Refactor is an agent skill from pproenca/dot-skills. Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring safety.
When should I use React Refactor?
React Refactor fits situations like: refactoring React codebases; reviewing PRs for architectural issues; decomposing oversized components; improving module boundaries.
How do I install React Refactor in Claude Code?
Run `npx skills add pproenca/dot-skills --skill react-refactor -a claude-code`. Or copy the skill folder (skills/.experimental/react-refactor in pproenca/dot-skills) into .claude/skills/react-refactor in your project. Claude Code loads it when a task matches its description.
How do I install React Refactor in Codex?
Run `npx skills add pproenca/dot-skills --skill react-refactor -a codex`. Or copy the skill folder (skills/.experimental/react-refactor in pproenca/dot-skills) into .agents/skills/react-refactor in your project. Codex loads it when a task matches its description.
Can I use React Refactor in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill react-refactor -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/react-refactor, .gemini/skills/react-refactor, .github/skills/react-refactor and .opencode/skills/react-refactor in your project.
What does React Refactor need to run?
SKILL.md names no scripts, command-line tools or credentials: React Refactor is instructions for the agent only.
Does React Refactor access the network?
SKILL.md names 4 domains. As links in the text: react.dev, kentcdodds.com, testing-library.com and patterns.dev. This is read from the text; nothing was executed.
Is React Refactor safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does React Refactor use?
React Refactor is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does React Refactor use?
About 2.3k tokens (SKILL.md is roughly 9.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 29k tokens, read only when the agent opens those files.
What are the alternatives to React Refactor?
Skills that share tags, products or a category with React Refactor: React Best Practices (shapeshift/web, 206 stars), React Performance (affaan-m/ECC, 274k stars), Vercel React Best Practices (sanity-io/sanity, 6.4k stars) and React Best Practices (ryokun6/ryos, 1.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains React Refactor?
pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 214 GitHub stars. The repository holds 182 skills in this directory. The repository was last updated on August 15, 2026.
Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.