react-code-smells

Original：🇺🇸 English

Translated

Principal-engineer-level React refactoring patterns for eliminating code smells. Covers prop drilling, state explosion, component composition, abstraction quality, coupling, hooks, rendering patterns, and testability. Use when refactoring existing React codebases, reviewing PRs for architectural issues, or identifying technical debt in React applications.

2installs

Sourcepproenca/dot-skills

Added on2026-02-09

NPX Install

npx skill4agent add pproenca/dot-skills react-code-smells

SKILL.md Content

View Translation Comparison →

Principal Engineering React Best Practices

Principal-engineer-level refactoring guide for React applications. Contains 42 rules across 8 categories, prioritized by impact from critical (state architecture, composition) to incremental (testability). Each rule includes code smell indicators, before/after examples, and safe transformation steps.

When to Apply

Reference these guidelines when:

Refactoring existing React codebases
Reviewing PRs for architectural issues
Identifying technical debt
Planning large-scale refactoring efforts
Deciding whether to extract, inline, or restructure components
Improving testability of React code

Rule Categories by Priority


state-
comp-
abs-
couple-
hook-
render-
effect-
test-

Priority	Category	Impact	Prefix
1	State Architecture	CRITICAL	`state-`
2	Component Composition	CRITICAL	`comp-`
3	Abstraction Quality	HIGH	`abs-`
4	Coupling & Cohesion	HIGH	`couple-`
5	Hook Hygiene	MEDIUM-HIGH	`hook-`
6	Render Patterns	MEDIUM	`render-`
7	Side Effect Management	MEDIUM	`effect-`
8	Testability	LOW-MEDIUM	`test-`

Quick Reference

1. State Architecture (CRITICAL)

```
state-prop-drilling-compound
```
- Replace prop drilling with compound components
```
state-prop-drilling-composition
```
- Replace prop drilling with component composition
```
state-derived-calculation
```
- Replace synchronized state with derived calculations
```
state-machine-complex
```
- Replace boolean explosion with state machines
```
state-colocation
```
- Colocate state with components that use it
```
state-reducer-consolidation
```
- Consolidate related useState calls into useReducer
```
state-context-selector
```
- Use context selectors to prevent cascade re-renders
```
state-url-sync
```
- Move shareable state to URL parameters

2. Component Composition (CRITICAL)

```
comp-render-props-extraction
```
- Extract shared logic with render props or hooks
```
comp-slots-over-props
```
- Use slots/children instead of configuration props
```
comp-god-component-split
```
- Split god components by responsibility
```
comp-controlled-uncontrolled
```
- Choose controlled vs uncontrolled deliberately
```
comp-headless-extraction
```
- Extract headless components for reusable behavior
```
comp-props-spreading
```
- Avoid untyped props spreading
```
comp-polymorphic-as
```
- Use polymorphic 'as' prop for flexible elements
```
comp-children-validation
```
- Validate compound component children

3. Abstraction Quality (HIGH)

```
abs-premature-abstraction
```
- Resist premature abstraction (Rule of Three)
```
abs-over-configuration
```
- Prefer composition over configuration
```
abs-extract-custom-hook
```
- Extract custom hooks for reusable logic
```
abs-inline-vs-extract
```
- Know when to inline vs extract components
```
abs-wrong-abstraction-fix
```
- Fix wrong abstractions by inlining first
```
abs-utility-vs-domain
```
- Separate utility hooks from domain hooks

4. Coupling & Cohesion (HIGH)

```
couple-colocation-files
```
- Colocate related files by feature
```
couple-dependency-injection
```
- Use dependency injection for external services
```
couple-interface-segregation
```
- Apply interface segregation to props
```
couple-circular-deps
```
- Break circular dependencies with inversion
```
couple-stable-imports
```
- Import from stable public APIs only

5. Hook Hygiene (MEDIUM-HIGH)

```
hook-dependency-stability
```
- Ensure hook dependencies are stable
```
hook-composition-over-size
```
- Compose small hooks rather than one large hook
```
hook-return-object-vs-tuple
```
- Choose hook return type by use case
```
hook-conditional-usage
```
- Never call hooks conditionally
```
hook-naming-conventions
```
- Follow hook naming conventions

6. Render Patterns (MEDIUM)

```
render-conditional-early-return
```
- Use early returns for conditional rendering
```
render-list-key-stability
```
- Use stable, unique keys for lists
```
render-avoid-inline-objects
```
- Avoid inline objects in JSX props
```
render-fragment-cleanup
```
- Use fragments to avoid wrapper divs

7. Side Effect Management (MEDIUM)

```
effect-to-event-handler
```
- Move event responses from effects to handlers
```
effect-cleanup-required
```
- Always clean up effect side effects
```
effect-single-responsibility
```
- Separate unrelated effects
```
effect-avoid-unnecessary
```
- Remove effects that aren't synchronization

8. Testability (LOW-MEDIUM)

```
test-seam-creation
```
- Create seams for testable components
```
test-behavior-over-implementation
```
- Test behavior, not implementation details
```
test-extract-for-testability
```
- Extract logic to hooks for testability
```
test-mock-boundaries
```
- Mock at boundaries, not internal details

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Related Skills

For React 19 API best practices, see
```
react
```
skill
For React core principles, see
```
react-principle-engineer
```
skill
For form handling, see
```
react-hook-form
```
skill

References

react.dev - Official React documentation
kentcdodds.com - Advanced React patterns
patterns.dev - Design patterns in JavaScript
testing-library.com - Testing best practices