Component refactoring

Component Refactoring

This skill helps separate UI, state, effects, and domain integrations when doing so improves cohesion, testing, or maintenance. The scanner produces advisory signals; size, hook count, and array calls are not defects or evidence of performance gains on their own.

Memory and patterns

Read the local MEMORY.md and follow ../.shared/SKILL-MEMORY-PROTOCOL.md; use node "<skills-root>/.shared/src/memory-cli.js" append ... for actionable results. The utility validates, renumbers, and retains up to 12 entries.

Before making decisions influenced by existing code, follow ../.shared/PATTERN-LEARNING-PROTOCOL.md and query the repository catalog with node "<skills-root>/.shared/src/pattern-learning/pattern-cli.js" query ...; after confirming a new or refined pattern in the code, consolidate it with node "<skills-root>/.shared/src/pattern-learning/pattern-cli.js" upsert ....

Compatibility and usage

Compatible with React 18/19, Vite 7/8, and Node 22.13+. It analyzes .jsx and .tsx with the repository's TypeScript parser without running the application:

node "<skill-dir>/scripts/scan-component-smells.js" ./src --format json --dry-run
node "<skill-dir>/scripts/scan-component-smells.js" ./src --threshold 180 --output ./validation-results/component --format markdown

The scanner ignores comments and strings when counting handlers and computations and returns action: review. Output behavior follows the shared CLI contract in ../.shared/README.md.

When not to use

• The goal is reducing re-renders of memoized subtrees; use the memoization-optimization skill.
• The problem is Context update propagation; use the state-management-optimization skill.
• The issue is bundle size or loading performance; use the bundle-optimization or holistic-performance skill.

Process

1. Record a baseline for behavior, tests, builds, and the critical-flow profile.
2. Run the scanner and manually confirm each signal in the code.
3. Separate by domain boundary, such as useUser, usePosts, or useUserForm, while keeping contracts explicit and return values small.
4. In useEffect, list every reactive dependency used. If execution has different causes, split the effects. If an API requires a stable reference, change the structure (or deliberately use a ref); never omit dependencies merely to silence lint.
5. For requests, handle loading, errors, cancellation or AbortController, and race conditions.
6. Preserve semantics, accessibility, and event order. Extract components only when there is real cohesion, reuse, or isolated testing value.
7. Repeat the same tests and profiling scenario. Fewer findings represent a structural change; call it a performance gain only when a reproducible metric improves.

React + Vite

• Keep component and hook modules simple for Fast Refresh; avoid module-scope side effects and exports that unnecessarily mix arbitrary values with components.
• Hooks are functions, not components: they do not return JSX as their primary responsibility and they follow the Rules of Hooks.
• In TSX, prefer explicit input and output types, and do not use any to hide dependencies.
• Vite does not change React's effect model; a fast build does not justify removing cleanup or dependencies.
• Never define a component inside another component: every render creates a new type, forcing a remount that loses state and DOM (focus loss, restarted effects). Extract it and pass props.
• Compute values derivable from props or state during render; do not mirror them in state synchronized by an effect.
• Run side effects triggered by a specific user action in that event handler, not in state + effect that re-runs on unrelated changes.

Limitations

The scanner cannot determine whether a useEffect has semantically correct dependencies, calculate complexity, measure re-renders, or replace ESLint, tests, or the Profiler. --threshold is a triage threshold, not a universal recommendation.

Files

• scripts/scan-component-smells.js: AST/JSX scanner and shared CLI.
• checklists/component-checklist.md: manual review and validation.
• examples/before and examples/after: the same dashboard flow, with logic extracted into hooks in the latter.