.tmp-cache-components-deferral.md

Deferring Next.js Cache Components (Express + custom handler phase)

One-liner: Cache Components are deferred until we’re off Express + custom Next; nginx + our existing Next usage are enough for now.

---

Decision

We are not adopting Next.js Cache Components (cacheComponents in next.config, 'use cache', cacheLife, etc.) while the application runs Express with the custom Next request handler.

Why this is reasonable (not “Next is bad”)

Cache Components are a supported Next 16 feature, but they introduce additional server-side caching semantics that sit alongside:

• nginx proxy_cache and explicit allow‑listed document routes
• HTTP Cache-Control on full HTML responses (often long s-maxage for PPR / prerendered shells)
• Next’s own output / route caching behavior

In our stack, those layers do not automatically line up. Inner cacheLife('seconds') does not necessarily shorten the document’s Cache-Control, so edge caches can pin HTML while developers assume the page “should have” refreshed. Debugging that requires understanding two products (nginx + Next) and which cache answered the request.

None of that is impossible to operate — it is extra complexity during a phase where we are still integrating Next behind nginx and Express.

What we are not giving up

Deferring Cache Components does not mean “no caching.” We still have:

• nginx: static assets, optional document caching for allow‑listed paths, deny‑by‑default routing
• Next: existing App Router patterns, data fetching, and explicit invalidation approaches the team already knows (e.g. revalidatePath / revalidateTag where appropriate — subject to how we host Next later)

We are only deferring this specific opt‑in cache API.

Fit with our migration plan

Today we want to introduce Next and stabilize Express + custom handler + nginx. Soon we intend to move away from the custom handler toward a more standard Next deployment shape.

Cache Components are easier to reconsider after:

• the hosting / server boundary is settled, and
• we are not paying compound complexity across Express + Next + nginx edge semantics

Team-facing summary

Proposal: We’re not adopting Next.js Cache Components (cacheComponents / 'use cache') while the app runs Express + the custom Next request handler. They don’t unlock anything we must have today, and they add extra cache layers and upgrade footguns on top of our nginx edge cache and closed-by-default routing. Once we move to a more standard Next hosting path and drop the custom handler, we can revisit Cache Components if the product needs that model.

---

Optional technical notes (for reviewers)

• Document vs segment: Edge caches key on HTTP responses. A page can be long‑lived at the document layer while inner regions use short server cache lifetimes — those concerns are orthogonal unless we design nginx and Next headers together.
• Custom server: Next’s docs and test matrix emphasize default hosting paths; Express + getRequestHandler() is a smaller, integration‑sensitive subset.
• Operational clarity: If Express logs are quiet, traffic may still be “successful” at nginx (HIT / 404 / static). Adding Cache Components increases the number of “which cache lied to me?” failure modes during incidents.

This document is a risk/complexity tradeoff, not a permanent ban on the feature.