---
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](references/async-rules.md) |
| 2 | Bundle Size Optimization | CRITICAL | [bundle-rules.md](references/bundle-rules.md) |
| 3 | Re-render Optimization | MEDIUM | [rerender-rules.md](references/rerender-rules.md) |
| 4 | Rendering Performance | MEDIUM | [rendering-rules.md](references/rendering-rules.md) |
| 5 | JavaScript Performance | LOW-MEDIUM | [js-rules.md](references/js-rules.md) |
| 6 | Advanced Patterns | LOW | [advanced-rules.md](references/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](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](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](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](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](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](references/advanced-rules.md) for detailed rules and code examples.