React performance optimization guidelines from Mastra Engineering. This skill should be used when writing, reviewing, or refactoring React code to ensure optimal performance patterns. Triggers on tasks involving React components, data fetching, bundle optimization, or performance improvements.
npxskills add mastra-ai/mastra--skill react-best-practicesLoading…
Routing and priority guide for React performance and quality, containing 26 rules across 9 categories. Rule files hold the detailed explanations, examples, review smells, and impact metrics.
Reference these guidelines when:
Rules are prioritized by impact:
| Priority | Category | Impact |
|---|---|---|
| 1 | Eliminating Waterfalls | CRITICAL |
| 2 | Bundle Size Optimization | CRITICAL |
| 3 | Client-Side Data Fetching | MEDIUM-HIGH |
| 4 | Re-render Optimization | MEDIUM |
| 5 | Rendering Performance | MEDIUM |
| 6 |
| JavaScript Performance |
| LOW-MEDIUM |
| 7 | Component Structure | MEDIUM-HIGH (maintainability) |
| 8 | Testing | MEDIUM-HIGH (correctness) |
| 9 | Type Safety | HIGH |
Eliminate Waterfalls:
Promise.all() for independent async operations (async-parallel)Reduce Bundle Size:
bundle-barrel-imports)bundle-defer-third-party)Client-Side Data Fetching:
client-request-dedupe)undefined, never | null or a fake fallback; narrow at the caller so hooks stay strict, or guard with skipToken when the hook must accept an optional param (client-request-dedupe)Re-render Optimization:
rerender-lazy-state-init)startTransition for non-urgent updates (rerender-transitions)rerender-useeffect-function-calls)useEffect; lift the discriminant and remount the branch (rerender-no-useeffect-state-reset)useMemo or useCallback; leave memoization decisions to developers with profiler evidence (rerender-no-usememo-usecallback)setState during render or inside useEffect; derive during render or move state ownership to an intermediate component (rerender-no-setstate-in-render-or-effect)Component Structure:
structure-single-responsibility)structure-narrow-apis)structure-component-naming)structure-derive-dont-duplicate)let-based render prep are code smells (structure-complex-derived-logic)if guards but keep the layout wrapper in one place — branch a body component, don't ternary or duplicate the shell (structure-early-return-render-branches)structure-composition-over-config)Testing:
@mastra/client-js + React Query stack and mock only the network; never vi.mock our own hooks/services/auth gating or the SDK (testing-bdd-no-mocks)testing-no-classname-assertions)Type Safety:
as type assertions anywhere — production or tests; narrow with real type guards, query generics (querySelector<T>, getByRole<T>), typed fixture factories, or implements on mocks. as const is the only allowed form. Do not replace a cast with a domain-type predicate that only checks typeof value === 'object'; call that an isRecord helper or validate the fields used (types-no-type-assertions)undefined and optional ? for absence, not null; convert external null at boundaries, and keep leaf props strict so callers own absence and fallback rendering (types-no-null)rendering-animate-svg-wrapper)content-visibility: auto for long lists (rendering-content-visibility)js-set-map-lookups)toSorted() instead of sort() for immutability (js-tosorted-immutable)js-length-check-first)Rule files are the canonical source for detailed guidance and examples:
references/react-best-practices-reference.md - Rule catalog with category order and rule-file pathsreferences/rules/ - Canonical individual rule files organized by categoryLoad only the relevant rule file when implementing or reviewing a specific pattern. Use the catalog to choose the right rule without loading every example.
To look up a specific pattern, grep the rules directory:
grep -l "Promise.all" references/rules/
grep -l "barrel" references/rules/
grep -l "Tanstack" references/rules/
references/rules/async-* - Waterfall elimination (1 rule)bundle-* - Bundle size optimization (2 rules)client-* - Client-side data fetching (1 rule)rerender-* - Re-render optimization (6 rules)rendering-* - DOM rendering performance (2 rules)js-* - JavaScript micro-optimizations (3 rules)types-* - Type-safety / no-as-cast and no-null rules (2 rules)structure-* - Component/hook/function/utility structure (7 rules)testing-* - BDD tests + mock-only-the-network policy + no className implementation-mirror assertions (2 rules)
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).