▋
app-dev/react/SKILL.md

name: react description: "React and TSX guidance: state and effects, memoization and React Compiler, TanStack Query server state, TanStack Router, SSR/hydration/Suspense, composition, accessibility, testing, and animations. Use when writing or reviewing React/TSX code or answering React architecture questions. Not for React Native/Expo (react-native-skills), Framer Motion internals (framer-motion), or React Flow canvases (react-flow-v12)."

React knowledge skill. The same knowledge drives editing and reviewing; only the lens differs.

1. Classify the task

Use the topic guides under references/topic-guides/.

Common routes:

  • state, useEffect, dependencies, derived values, event handlers -> references/topic-guides/effects-and-derived-state.md
  • useMemo, useCallback, memo, re-render tuning, compiler -> references/topic-guides/performance-and-memoization.md
  • TanStack Query, server state, query keys, queryOptions, prefetching, mutations -> references/topic-guides/tanstack-query-server-state.md
  • composition, file structure, component extraction, barrel files, compound components -> references/topic-guides/composition-and-structure.md
  • accessibility, tests, test ids, ARIA, roles, labels -> references/topic-guides/a11y-and-testing.md
  • animations, transitions, Framer Motion, AnimatePresence, View Transitions, gestures, prefers-reduced-motion -> references/topic-guides/animations.md
  • router, SSR, hydration, Suspense, streaming, Server Components -> references/topic-guides/router-ssr-and-hydration.md

If the task spans multiple topics, load the primary guide first, then one secondary guide if truly needed.

2. Source precedence

When local guidance conflicts or feels incomplete:

  1. official React docs and official React blog
  2. official library docs for the exact library in use
  3. maintainer sources such as TkDodo
  4. curated community sources
  5. local taste or stylistic preference

TkDodo style is valuable, but treat it as high-quality maintainer guidance rather than universal law.

3. When to fetch live docs

Always prefer current canonical docs for:

  • React Compiler
  • release-specific behavior
  • deprecated patterns or setup guidance
  • Server Components
  • Actions
  • Suspense, SSR, hydration, streaming
  • TanStack major-version-sensitive APIs
  • router integrations

Use references/source-registry.json to find canonical sources. When a canonical page is cached locally under cache/sources/, read the cached file first; verify against the live URL only if the task is version-sensitive or the cache looks incomplete.

3b. Deep maintainer reference (TkDodo)

TkDodo's guidance is pre-distilled into the topic-guide principles — apply those directly; you rarely need the articles themselves. Read a cached article only when:

  1. the topic guide's "Deep dives" list points at one for your exact problem (edge cases, tradeoff detail, exact APIs), or
  2. the question involves recent posts or APIs that may postdate model training — check the published field in references/tkdodo-index.json and prefer reading any post published after your training cutoff over answering from memory.

Full text lives at cache/sources/tkdodo/<slug>.md (HTML-stripped markdown); the index lists every post with slug, title, description, and date. Never read more than ~2 posts per task. If a cache file is missing, WebFetch the post's url from the index. For version-sensitive APIs, current official docs beat any blog post.

4. Editing defaults

Default to these unless the codebase has a stronger local rule:

  • prefer derived state over effect-synced state
  • treat effects as integration boundaries: feature code defaults to zero; when React must synchronize with an external system, keep the effect in the smallest component or hook that owns it, with honest dependencies and symmetric cleanup
  • use event handlers for event-specific logic
  • prefer local state and composition before memoization
  • justify manual memoization
  • separate server state from client state
  • start with invalidation after mutations unless a precise cache write is clearly safer
  • prefer accessible selectors over test ids
  • prefer simple, local code over abstraction theater

5. Review checks

Run a lightweight self-review after edits. Run the full list when asked to review a diff or scope.

State and effects

  • state copied from props or from other state without a good reason
  • effects used to derive values that should be calculated during render
  • event-specific logic hidden in an effect
  • dependency workarounds that dodge the real data-flow problem

Performance and memoization

  • useMemo, useCallback, or memo added without a clear bottleneck or contract reason
  • memoization used to patch over impurity or effect churn
  • compiler-sensitive code that assumes old memoization habits are still ideal

TanStack Query and server state

  • server state copied into local state unnecessarily
  • custom wrappers that make query definitions harder to share or type
  • mutation flows that should likely invalidate rather than manually rewrite many caches
  • query keys and reusable query definitions that are inconsistent or weakly structured

Composition and structure

  • giant conditional components that should be composed differently
  • barrel files or indirection that obscure ownership and dependencies
  • abstractions introduced before simpler local extraction was attempted

Accessibility and tests

  • data-testid used where role, label, text, or accessible name should work
  • component APIs that make accessibility harder instead of easier
  • tests coupled to implementation details rather than user-visible behavior

Animations

  • effects used to drive animation progress that the library or CSS should own
  • entrance/exit animations modeled with conditional state and effects instead of key changes or AnimatePresence
  • prefers-reduced-motion not handled, or handled only in the CSS but bypassed by JS-driven animations
  • animations that block input, hide focus, or break the accessible path during the transition

Router, SSR, hydration, Suspense

  • assumptions that depend on framework or version details without checking current docs
  • hydration-sensitive code paths that differ between server and client without explanation

6. Output format

When the task is editing code, just make the changes and finish with a short self-review.

When the task is an explicit review, return:

  • Passes: things that look solid
  • Concerns: each with severity: high|medium|low
  • Suggested refactors: practical changes in priority order
  • Source notes: only when the conclusion depends on version-sensitive guidance

7. Maintenance

The topic guides and tkdodo-index.json are generated — edit references/manual-topic-map.json, never the guides directly. To refresh sources and regenerate:

node scripts/sync-sources.mjs
node scripts/build-topic-index.mjs