workleap-react-best-practices

name	workleap-react-best-practices
description	React performance optimization guidelines for Single Page Applications (SPA) at Workleap. Use when writing, reviewing, or refactoring React SPA code. Covers async waterfall elimination, bundle size reduction, re-render optimization, rendering efficiency, JS micro-optimizations, and advanced patterns. Activate even for small component changes — performance regressions compound silently. Does not cover SSR, Next.js, or server components.
metadata	{"version":1.1}

Workleap React Best Practices

Performance optimization guide for React Single Page Applications (SPA), tailored for Workleap's SPA-first architecture.

When to Apply

Reference these guidelines when:

• Writing new React components
• Reviewing code for performance issues
• Refactoring existing React code
• Optimizing bundle size or load times
• Debugging unnecessary re-renders

Rule Categories by Priority

Priority	Category	Impact	Reference
1	Eliminating Waterfalls	CRITICAL	async-rules.md
2	Bundle Size Optimization	CRITICAL	bundle-rules.md
3	Re-render Optimization	MEDIUM	rerender-rules.md
4	Rendering Performance	MEDIUM	rendering-rules.md
5	JavaScript Performance	LOW-MEDIUM	js-rules.md
6	Advanced Patterns	LOW	advanced-rules.md

Quick Reference

1. Eliminating Waterfalls (CRITICAL)

Waterfalls are the #1 performance killer. Each sequential await adds full network latency.

• Defer Await Until Needed - Move await into branches where actually used
• Promise.all() for Independent Operations - Run independent async operations concurrently
• Dependency-Based Parallelization - Use promise chaining for partial dependencies
• Prevent Waterfall Chains - Start promises early, await late

Read references/async-rules.md for detailed rules and code examples.

2. Bundle Size Optimization (CRITICAL)

Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.

• Route-Based Code Splitting - Lazy-load each route so users only download code they visit
• Avoid Barrel File Imports - Import directly from source files, not barrel re-exports
• React.lazy for Heavy Components - Lazy-load large components not needed on initial render
• Conditional Module Loading - Load modules only when feature is activated
• Preload on User Intent - Preload heavy bundles on hover/focus

Read references/bundle-rules.md for detailed rules and code examples.

3. Re-render Optimization (MEDIUM)

Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.

• Defer State Reads - Don't subscribe to state only used in callbacks
• Extract to Memoized Components - Enable early returns before computation
• Hoist Default Non-primitive Props - Extract default values to constants for stable memo
• Narrow Effect Dependencies - Use primitive dependencies in effects
• Subscribe to Derived State - Subscribe to derived booleans, not raw values
• Calculate Derived State During Render - Derive state during render, not effects
• Functional setState - Use functional setState for stable callbacks
• Lazy State Initialization - Pass function to useState for expensive values
• Skip useMemo for Simple Expressions - Avoid memo for simple primitives
• Put Logic in Event Handlers - Put interaction logic in event handlers, not effects
• Transitions for Non-Urgent Updates - Use startTransition for non-urgent updates
• useRef for Transient Values - Use refs for transient frequent values

Read references/rerender-rules.md for detailed rules and code examples.

4. Rendering Performance (MEDIUM)

Optimizing the rendering process reduces the work the browser needs to do.

• Animate SVG Wrapper - Animate div wrapper, not SVG element
• CSS content-visibility - Use content-visibility for long lists
• Hoist Static JSX - Extract static JSX outside components
• Optimize SVG Precision - Reduce SVG coordinate precision
• Activity Component (Experimental) - Use Activity for show/hide with state preservation
• Explicit Conditional Rendering - Use ternary, not && for conditionals
• useTransition for Loading - Prefer useTransition over manual loading state

Read references/rendering-rules.md for detailed rules and code examples.

5. JavaScript Performance (LOW-MEDIUM)

Micro-optimizations for hot paths that can add up to meaningful improvements.

• Avoid Layout Thrashing - Batch DOM writes, avoid interleaved reads
• Build Index Maps - Use Map for repeated lookups
• Cache Property Access - Cache object properties in loops
• Cache Function Results - Cache repeated function calls in module-level Map
• Cache Storage API Calls - Cache localStorage/sessionStorage reads
• Combine Array Iterations - Combine multiple filter/map into one loop
• Early Length Check - Check array length before expensive comparison
• Early Return - Return early from functions
• Hoist RegExp - Hoist RegExp creation outside loops
• Loop for Min/Max - Use loop instead of sort for min/max
• Set/Map Lookups - Use Set/Map for O(1) lookups
• toSorted() Immutability - Use toSorted() to prevent mutation bugs

Read references/js-rules.md for detailed rules and code examples.

6. Advanced Patterns (LOW)

Advanced patterns for specific cases that require careful implementation.

• Event Handler Refs - Store event handlers in refs for stable subscriptions
• Initialize Once - Initialize app once per load, not per mount
• Stable Callback Refs - Stable callback refs for effects without re-runs

Read references/advanced-rules.md for detailed rules and code examples.