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.