React Best Practices
Give your coding agent a prioritized React performance rulebook while you build or refactor UI in a solo SaaS or dashboard.
Overview
React Best Practices is an agent skill most often used in Build (also Ship perf and review) that applies 12 prioritized React performance rules when generating, maintaining, or refactoring front-end code.
Install
npx skills add https://github.com/mastra-ai/mastra --skill react-best-practicesWhat is this skill?
- 12 prioritized performance rules across 6 impact tiers—from CRITICAL waterfalls and bundle size through MEDIUM re-render
- CRITICAL guidance: parallelize independent work with Promise.all() and eliminate request waterfalls
- CRITICAL bundle rules: avoid barrel imports and defer non-critical third-party libraries
- MEDIUM-HIGH client fetching: TanStack Query for automatic request deduplication
- Each rule ships incorrect vs. correct examples and impact notes tuned for AI-assisted refactors
- 12 performance rules across 6 categories
- Rules span CRITICAL, MEDIUM-HIGH, and MEDIUM impact tiers
- Document version 0.2.0 (Mastra Engineering, January 2026)
Adoption & trust: 1.1k installs on skills.sh; 24.9k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your React app feels slow, bundles bloat, and your agent keeps introducing waterfalls, barrel imports, and avoidable re-renders.
Who is it for?
Solo builders shipping React SaaS, dashboards, or internal tools who want agents to enforce Mastra-style performance rules during implementation and targeted refactors.
Skip if: Non-React stacks, backend-only services, or teams that only need visual design without performance-sensitive React implementation.
When should I use this skill?
Maintaining, generating, or refactoring React codebases when you want consistent, impact-prioritized performance rules applied by the agent.
What do I get? / Deliverables
Refactored or newly generated React code follows the 12 categorized rules—with parallel fetching, lean imports, TanStack Query deduplication, and render discipline—as the acceptance bar.
- React components and hooks aligned to the 12 prioritized rules
- Refactors that document incorrect vs. correct patterns per rule category
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
React UI is authored and iterated during Build; this skill’s triggers target generating, maintaining, and refactoring React codebases—the core frontend implementation shelf. All 12 rules target client React patterns (fetching, bundles, re-renders), which map directly to frontend implementation rather than backend or agent-tooling work.
Where it fits
Wire a settings dashboard so independent API calls run in parallel instead of serial waterfalls.
Replace heavy barrel imports with direct module paths while adding a new feature area.
Pre-launch pass to defer non-critical third-party scripts and shrink the main bundle.
Review a PR for TanStack Query usage and redundant parent re-renders before merge.
How it compares
Use as a fixed rulebook during codegen and refactors instead of one-off React performance tips in chat.
Common Questions / FAQ
Who is react-best-practices for?
Solo and indie builders (and small teams) using Claude Code, Cursor, Codex, or similar agents to write, maintain, or refactor React front ends where load time and render cost matter.
When should I use react-best-practices?
During Build frontend work when generating components or wiring client data; during Ship perf passes before launch to audit bundles and waterfalls; and during Ship review when judging PRs for re-render and import patterns.
Is react-best-practices safe to install?
It is documentation-style procedural guidance with no built-in network or shell requirements from the skill itself; review the Security Audits panel on this Prism page before trusting any third-party skill in your repo.
SKILL.md
READMESKILL.md - React Best Practices
# React Best Practices **Version 0.2.0** Mastra Engineering January 2026 > **Note:** > This document is mainly for agents and LLMs to follow when maintaining, > generating, or refactoring React codebases. Humans > may also find it useful, but guidance here is optimized for automation > and consistency by AI-assisted workflows. --- ## Abstract Performance optimization guide for React applications, designed for AI agents and LLMs. Contains 12 rules across 6 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (JavaScript micro-optimizations). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation. --- ## Table of Contents 1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL** - 1.1 [Promise.all() for Independent Operations](#11-promiseall-for-independent-operations) 2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL** - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports) - 2.2 [Defer Non-Critical Third-Party Libraries](#22-defer-non-critical-third-party-libraries) 3. [Client-Side Data Fetching](#3-client-side-data-fetching) — **MEDIUM-HIGH** - 3.1 [Use TanStack Query for Automatic Deduplication](#31-use-tanstack-query-for-automatic-deduplication) 4. [Re-render Optimization](#4-re-render-optimization) — **MEDIUM** - 4.1 [Use Lazy State Initialization](#41-use-lazy-state-initialization) - 4.2 [Use Transitions for Non-Urgent Updates](#42-use-transitions-for-non-urgent-updates) - 4.3 [useEffectEvent for Functions in useEffect](#43-useeffectevent-for-functions-in-useeffect) 5. [Rendering Performance](#5-rendering-performance) — **MEDIUM** - 5.1 [Animate SVG Wrapper Instead of SVG Element](#51-animate-svg-wrapper-instead-of-svg-element) - 5.2 [CSS content-visibility for Long Lists](#52-css-content-visibility-for-long-lists) 6. [JavaScript Performance](#6-javascript-performance) — **LOW-MEDIUM** - 6.1 [Early Length Check for Array Comparisons](#61-early-length-check-for-array-comparisons) - 6.2 [Use Set/Map for O(1) Lookups](#62-use-setmap-for-o1-lookups) - 6.3 [Use toSorted() Instead of sort() for Immutability](#63-use-tosorted-instead-of-sort-for-immutability) --- ## 1. Eliminating Waterfalls **Impact: CRITICAL** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains. ### 1.1 Promise.all() for Independent Operations When async operations have no interdependencies, execute them concurrently using `Promise.all()`. **Incorrect (sequential execution, 3 round trips):** ```typescript const user = await fetchUser(); const posts = await fetchPosts(); const comments = await fetchComments(); ``` **Correct (parallel execution, 1 round trip):** ```typescript const [user, posts, comments] = await Promise.all([fetchUser(), fetchPosts(), fetchComments()]); ``` --- ## 2. Bundle Size Optimization **Impact: CRITICAL** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint. ### 2.1 Avoid Barrel File Imports Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`). Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts. **Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph. **Incorrect (imports entire library):** ```tsx import { Check, X, Menu }