adrianbrowning/react-router-loader-performance

React Router Loader Performance

Critical optimization techniques for React Router v7 loaders. Contains 4 rules focused on eliminating waterfalls and maximizing parallel execution.

Impact: CRITICAL - Poor loader performance directly impacts Time To First Byte (TTFB) and perceived page speed.

When to Apply

Use these techniques when:

• Loader TTFB exceeds 500ms
• Multiple database queries execute sequentially
• Secondary data (recommendations, analytics) blocks critical path
• Database latency is high (>50ms per query)
• Optimizing React Router v7 data loading patterns

Rules Summary

Database Optimization (CRITICAL)

loader-consolidate-queries - @rules/loader-consolidate-queries.md

Use ORM includes/relations for single-query data fetching.

// Bad: 3 DB calls (~450ms on 150ms latency)
const product = await db.product.findUnique({ where: { id } });
const reviews = await db.review.findMany({ where: { productId: id } });
const variations = await db.variation.findMany({ where: { productId: id } });

// Good: 1 DB call (~200ms)
const product = await db.product.findUnique({
  where: { id },
  include: { reviews: true, variations: true },
});

Impact: Often the single biggest loader performance win, especially on high-latency DB connections.

Streaming Optimization (HIGH)

loader-defer-slow-secondary - @rules/loader-defer-slow-secondary.md

Stream non-critical data without awaiting.

// Bad: blocks on slow operation (~3500ms TTFB)
const product = await getProduct(id); // 500ms
const recommendations = await getRecommendations(product); // 3000ms
return data({ product, recommendations }); // TTFB: 3500ms

// Good: streams secondary data (~500ms TTFB)
const product = await getProduct(id); // 500ms
const recommendations = getRecommendations(product); // Don't await
return data({ product, recommendations }); // TTFB: 500ms

Impact: Keeps slow operations off critical path. Recommendations stream while user views product.

Infrastructure Optimization (HIGH)

infrastructure-colocation

Minimize geographic distance between servers and databases.

Key metrics:

• Same region: <10ms latency
• Cross-region: 50-200ms latency
• Cross-continent: >100ms latency

Actions:

1. Host DB and servers in same cloud region
2. Use read replicas near application servers for read-heavy routes
3. Analyze ORM query logs for consistent >30ms latency
4. When DB latency is high, infrastructure changes provide greater gains than code optimization

Parallel Execution (CRITICAL)

promise-all-independent

Use Promise.all for independent async operations (covered in frontend-async-best-practices).

// Bad: sequential (~900ms)
const product = await fetchProduct(); // 400ms
const reviews = await fetchReviews(); // 300ms
const variations = await fetchVariations(); // 200ms

// Good: parallel (~400ms)
const [product, reviews, variations] = await Promise.all([
  fetchProduct(),
  fetchReviews(),
  fetchVariations(),
]);

Impact: Total time equals slowest operation, not sum of all operations.

Performance Targets

• TTFB: <500ms for critical path
• DB latency: <30ms per query (measure with ORM logs)
• Secondary data: Stream anything >1000ms that's non-critical

Measurement

Use Server-Timing headers to identify bottlenecks:

import { time } from "~/utils/timing.server";

export async function loader({ params }: Route.LoaderArgs) {
  const product = await time("product", () => getProduct(params.id));
  const recommendations = time("recommendations", () =>
    getRecommendations(product)
  );
  return data({ product, recommendations });
}

Analyze Chrome DevTools Network tab for Server-Timing breakdown.