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

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.