web-performance

Web Performance Skill

Version: 1.0 Stack: Apollo Client/Server + Redis + CloudFront + S3

Performance problems are invisible during development. Local servers are fast. Test data is small. You don't notice the 3MB bundle, the N+1 queries, or the full-table scan until real users on real connections with real data report that the page takes 8 seconds to load. By then, fixing it requires rearchitecting the caching layer, splitting the bundle, and rewriting queries — all at once, under pressure.

Performance patterns applied from the start are cheap. Performance fixes applied after launch are expensive. These rules are the cheap version.

---

Core Principles

1. Measure First — Profile before optimizing. Don't guess.
2. Cache at Every Layer — CDN → API → Database → In-Memory.
3. Minimize Payload — Send only what's needed.
4. Defer Non-Critical — Load critical path first, everything else later.
5. Perceived Performance — Optimistic UI makes things feel faster.

---

Core Web Vitals Targets

Metric	What It Measures	Target	Critical
LCP (Largest Contentful Paint)	Main content loaded	< 2.5s	< 4s
INP (Interaction to Next Paint)	Input responsiveness	< 200ms	< 500ms
CLS (Cumulative Layout Shift)	Visual stability	< 0.1	< 0.25

---

Apollo Client Caching

Configure InMemoryCache with type policies for pagination merging and computed fields. Use cache-and-network as default fetch policy (stale-while-revalidate). Use optimistic updates for mutations to make UI feel instant.

Fetch Policies

Policy	Use Case
cache-first	Static data (categories, config)
cache-and-network	Data that changes (products, user data)
network-only	Always fresh (order status, real-time)
cache-only	Offline mode, known-cached data

See assets/caching-patterns.md for cache configuration, fetch policy examples, and optimistic update patterns.

---

Redis Caching

Cache-aside pattern: check cache → miss → fetch DB → store in cache. Invalidate on writes. Use tag-based invalidation for list queries.

TTL Guidelines

Data Type	TTL	Reason
Static config	24h+	Rarely changes
Product catalog	1h	Changes occasionally
User sessions	30m	Security balance
Cart data	7d	User convenience
Search results	5m	Balance freshness/speed
Real-time data	No cache	Must be live

See assets/caching-patterns.md for Redis cache service, cache-aside pattern, and invalidation examples.

---

CloudFront & S3 Optimization

Immutable assets (hashed filenames) get 365-day cache. API routes get no CDN caching. Images get resize-on-demand with WebP format, lazy loading, and 2x srcSet for retina.

See assets/caching-patterns.md for CDK configuration and image optimization component.

---

Bundle Optimization

Route-based code splitting with React.lazy. Dynamic imports for heavy libraries (load only when needed). Analyze with source-map-explorer.

Bundle Size Guidelines

Category	Target	Action if Exceeded
Initial JS	< 100KB gzipped	Code split, tree shake
Vendor chunk	< 150KB gzipped	Lazy load, find alternatives
Route chunk	< 50KB gzipped	Split further
Total initial load	< 200KB gzipped	Audit dependencies

See assets/optimization-patterns.md for code splitting, dynamic import, and bundle analysis examples.

---

React Performance

Use useMemo for expensive computations, useCallback for stable callbacks passed to memoized children, and memo for list item components. Don't memoize simple values, always-changing values, or handlers on non-memoized children. Use virtualization for long lists (100+ items).

See assets/optimization-patterns.md for memoization, when-NOT-to-memoize, and virtualization examples.

---

Database Performance

Select only needed fields. Use include sparingly. Use raw queries for complex aggregations. Add compound indices on filtered/sorted columns.

See assets/optimization-patterns.md for Prisma query optimization and index strategy.

---

Anti-Patterns

Anti-Pattern	Problem	Fix
Fetching all fields	Over-fetching, slow	Select only needed fields
No pagination	Memory issues, slow	Cursor-based pagination
Cache everything	Stale data, complexity	Cache strategically by TTL
Premature optimization	Wasted effort	Measure first, optimize hotspots
Sync heavy operations	Blocks response	Background jobs (Bull)
No CDN for static assets	Slow global delivery	CloudFront for static files
Unoptimized images	Huge downloads	Resize, compress, WebP
Blocking bundle	Slow initial load	Code split, lazy load

---

Checklist

Frontend

• Code split by route
• Heavy libraries lazy loaded
• Images lazy loaded
• Images optimized (WebP, sized)
• Bundle < 200KB initial
• useMemo/useCallback where beneficial
• Long lists virtualized

Apollo

• Cache policies configured
• Pagination merges correctly
• Optimistic updates for mutations
• Fetch policy matches data freshness needs

Redis

• Hot data cached
• TTLs appropriate for data type
• Cache invalidation on updates
• Connection pooling configured

Database

• Indices on filtered/sorted columns
• Select only needed fields
• N+1 queries eliminated (DataLoader)
• Expensive queries analyzed

CDN

• Static assets on CloudFront
• Immutable assets cached forever
• Dynamic content not cached at edge
• HTTPS enforced

---

When to Consider Alternatives

Situation	Consider
Global real-time data	Redis Pub/Sub or WebSockets
Heavy computation	Background workers (Bull)
Large file uploads	Direct S3 presigned URLs
Search-heavy	Elasticsearch or Algolia
Edge computing needs	CloudFront Functions or Lambda@Edge

---

References

• assets/caching-patterns.md — Apollo cache config, Redis, CloudFront, image optimization
• assets/optimization-patterns.md — Bundle splitting, React memoization, virtualization, DB optimization