Performance and caching

Performance and caching

HeadlessWP Pro performs best when you split traffic into public cacheable reads and user-specific no-store flows.

1) Know what is cacheable

Generally cacheable (public/catalog)

• Product lists and detail reads
• Offers and promotions feeds
• Content that does not vary by user session

Generally not cacheable (user/session)

• /me and entitlement payloads
• Cart reads and cart mutations
• Checkout, payment, and coupon operations
• Any endpoint that depends on cookies or user identity

If you cache user-specific responses, treat them as private:

• Vary cache keys by user identity or token
• Keep TTLs short
• Never share cached entries across users

2) Proxy and boundary reminder

For this repo, browser requests must go to Next.js route handlers, and WordPress traffic goes through /api/secure/**.

• Proxied API responses are no-store by contract.
• Do not configure CDN caching for /api/secure/**.
• Cache only truly public GET reads at the edge.

3) Safe frontend caching patterns

• Use in-memory or short-lived client caches only for public, non-authenticated reads.
• Do not cache authenticated responses in shared browser storage where users can cross sessions.
• Use stale-while-revalidate patterns for public docs/catalog reads.
• On failures, log correlation IDs so frontend incidents can be tied to backend logs.

4) CDN and server strategy

• Cache only public GET routes.
• Strip cookies on CDN-cached public routes.
• Avoid caching 401, 403, and 429 responses.
• Keep service keys server-side only.
• Use short revalidation windows for catalog data; bypass cache for /me, cart, and checkout flows.

5) Rate limiting and request-size notes

• Expect rate limiting on sensitive endpoints; implement exponential backoff for retryable failures (especially 429).
• Debounce repeated mutation attempts in UI flows.
• Keep request payloads intentionally small and validated before submission.

6) Do this first checklist

1. Classify each route as public-cacheable or user-specific.
2. Keep /api/secure/** no-store and uncached at CDN.
3. Cache only public GET reads with explicit TTLs.
4. Add retry backoff and debounce for mutation-heavy UI.
5. Track 5xx, login failures, 429 rates, and checkout errors.
6. Include correlation ID capture in frontend error logging.