Feature: First-party cache-revalidation subscriber/recipe for Next.js storefronts + guaranteed event surface

[dishanagalawatta]

Originally opened as issue #17802 — closed by the triage bot with a pointer here.

Context

The documented Next.js caching recipe (unstable_cache + getCacheTag + a hand-rolled /api/revalidate route + hand-written subscribers) is the single most-copied customization pattern in the Medusa docs — and every storefront re-implements it from scratch. The friction shows up repeatedly in the tracker:

• Proper data revalidation in Medusa with Next.js #11679 — "Proper data revalidation in Medusa with Next.js" (closed as docs)
• [Bug]: getCacheTag(tag) empty in api/revalidate/route.ts in Next.js storefront #11897 — "getCacheTag(tag) empty in api/revalidate/route.ts" (closed after fixes)
• [Bug]: Inventory updates do not emit Events, preventing Cache Revalidation #11691 — "Inventory updates do not emit Events, preventing Cache Revalidation" (closed as not planned — the underlying gap remains)

We operate an OpenNext/Cloudflare storefront on Medusa 2.22.6 and maintain this exact stack in production. Three gaps make it fragile for every project:

1. The whole chain is per-project boilerplate

Subscriber wiring → event-to-tag resolution → token-authed revalidate endpoint → timeout/fire-and-forget semantics. None of it is versioned or tested by the core team; every storefront forks its own copy that rots independently.

2. The event-name contract is a trap

Admin workflows emit short names (product.updated, product-variant.updated) while the events reference documents namespaced module names (product.product.updated). Subscribing to the wrong set silently does nothing. We maintain both spellings in our subscriber events "just in case" — this should be one documented contract.

3. The event surface the recipe depends on has holes

Stock/level mutations (the exact data most cached on product pages) do not reliably emit events — #11691 was closed as not planned, and the events reference has no inventory-level entries. Price-list and promotion flows are inconsistent in the same way. The recipe's correctness silently depends on events core doesn't guarantee.

Proposed solution

1. First-party reference implementation. Either:
   • a small official plugin (e.g. @medusajs/storefront-revalidation) shipping: a configurable event→tag map, a fire-and-forget subscriber (never blocks the admin write, AbortSignal.timeout-bounded POST with a shared-secret header, warn-on-failure logging, fail-safe over-purge on unknown events), and a matching reference /api/revalidate handler for Next.js; or
   • a maintained, tested recipe inside the official Next.js starter that the docs point to instead of inline snippets.
2. Document the event-name contract (short workflow names vs namespaced module names) explicitly in the events reference.
3. Guarantee the events the recipe needs: inventory-level and stock-location mutations should emit consistent events so cached availability data can be invalidated.

Reference implementation (running in production on Medusa 2.22.6)

Our subscriber (~90 lines, two files) follows exactly this contract: token header, 10s timeout, never throws into the admin write path, logs-and-returns when STORE_URL/REVALIDATE_SECRET are absent, and revalidates by tag with a read-back fallback on delete events (payload is ids-only) plus an over-purge on unknown entity types. Happy to contribute it as the seed for (1).