DEVEX-1485: Consolidate cache profiles ahead of Cloudflare compatibility work

[CNanninga]

Description

Groundwork for hosting this app on Cloudflare Workers. Cloudflare can't run Cache Components: the PPR staged-render path corrupts streamed HTML on workerd via @opennextjs/cloudflare — chunks of the RSC flight payload get emitted outside their <script> wrapper and render as raw JSON on the page. That's tracked upstream in opennextjs-cloudflare#1225 and #1318, and no released adapter version fixes it. A Cloudflare build therefore has to cache at the fetch level instead.

This PR changes no caching behavior. It moves the parts that don't depend on where caching attaches into one module with the same name and shape it has on the Cloudflare branch, so the two implementations differ only where they genuinely must.

Consolidates the profiles and the enable switch into lib/cache/cache-profiles.ts. cacheLife accepts an inline { stale, revalidate, expire } object as well as a named profile, so the durations no longer need a cacheLife block in next.config.ts. Each use cache boundary now selects one with cacheLife(cacheProfile(CACHE_PROFILE_STANDARD)), and isCachingEnabled lives beside the profiles it gates rather than in the Next config. The module sits under lib/cache rather than lib/bc-api-client because it describes the app's caching policy, not that client — one of the boundaries selecting a profile is fetchStoreExtensionStatus, which reads the credentials store and never calls the API.

Renames CACHE_COMPONENTS_ENABLED to CACHE_ENABLED. The old name described the cacheComponents flag it used to work around by overriding profiles. It now simply switches caching on and off, and the Cloudflare branch has no such flag for the name to refer to. CHANGELOG.md keeps the old name, since that entry records a released version.

Adds a real profile interface and name constants. CacheLifetimeProfile types the profile constants and cacheProfile's return value. All three fields are required, unlike Next's own CacheLife where each is optional: every profile here sets all three, and leaving one implicit would silently inherit Next's default rather than this app's intent. CACHE_PROFILE_STANDARD / CACHE_PROFILE_EXTENDED let call sites name a profile by constant instead of repeating a bare string; PROFILES is keyed by those constants and checked with satisfies, so CacheProfile still derives from the map and an unknown name remains a type error.

Every "use cache: remote" directive, every cacheTag / updateTag call, and all four duration values are unchanged.

Verification

• tsc --noEmit — clean

• eslint src/ — 0 errors (11 pre-existing warnings in postgres-driver-loader.unavailable.ts, unrelated)

• next build — succeeds; all 12 PPR routes still build as ◐, confirming Cache Components is untouched

• Type enforcement checked with a throwaway type-test: an unknown profile name and an incomplete profile object are both rejected

• Behavioral equivalence against unmodified main, measured side by side in a separate worktree:

  	main (baseline)	this branch
  CACHE_ENABLED=true: /gift-certs req 1 / repeat / /customers	3 / +0 / +2	3 / +0 / +2
  CACHE_ENABLED=false: same	3 / +3 / +2	3 / +3 / +2
  PPR routes	12	12

  Identical in every cell. (Counts are upstream BigCommerce API requests. Note the app's own request logger runs inside Next's patched fetch, so it also logs cache-served responses — hit/miss flags and sub-millisecond durations are the reliable signal, not raw log counts.)

Follow-up

• Per AGENTS.md, these changes still need replicating onto the progressive history via bcedu-lab-sync + validate-sync. Not included here.
• The fetch-level caching implementation this is converging toward lives on feature/gift-certs-manager-cloudflare-no-remote-cache, which is not part of this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
starter-sc-app-next	Ready	Preview	Aug 27, 2026 8:22pm