Invalidación de la caché del storefront

Estado: pendiente, sin historia asignada. Este documento registra un hueco encontrado el 2026-09-22 mientras se exploraba RF-009, para retomarlo después. No es parte de ese requisito: lo condiciona, igual que condiciona a todo lo demás que se publica desde el CMS.

El hueco

Cuando se publica o se corrige una página en el CMS, nadie le avisa al storefront. La página nueva aparece cuando a la caché del storefront se le vence el plazo, y no antes.

La pregunta que lo destapó fue exactamente esa: cuando se publica una página, ¿cómo sabe el front que tiene que limpiar su caché, o que la próxima consulta debe volver a preguntarle a Payload? Hoy no lo sabe. Solo espera.

Lo medido

Qué	Dónde	Estado
Lecturas del storefront a Payload	storefront/src/lib/payload.ts	Centralizadas en un solo módulo, con revalidación por tiempo de 60 segundos por defecto
Cabecera y navegación	src/lib/services/header-service.ts, navigation-service.ts	60 segundos
Cotización	src/lib/services/cotizacion-service.ts	3600 segundos
Punto de entrada de revalidación en el storefront	—	No existe. No hay ninguna ruta bajo src/app que revalide nada
Etiquetas de caché en las lecturas a Payload	src/lib/payload.ts	No se usan. Ninguna lectura declara next: { tags }
REVALIDATE_SECRET	check-env-variables.js, los .env de los tres entornos	Declarada y sin uso. El runbook del storefront ya la señala como configuración inerte, con el valor supersecret del starter de Medusa, idéntico en los tres entornos
Ganchos de revalidación en el CMS	src/collections/Pages/hooks/revalidatePage.ts, src/hooks/revalidateRedirects.ts	Existen y funcionan, pero revalidan la caché del sitio Next del propio CMS, no la del storefront

Ese último renglón es el que confunde: el CMS parece tener resuelta la revalidación. La tiene, para su propio sitio. revalidatePath y revalidateTag actúan sobre el proceso donde se ejecutan, y el storefront es otra aplicación, en otro contenedor. El CMS no tiene manera de alcanzarlo llamando a una función local.

Qué pasa hoy al publicar

1. Se publica la página en el CMS.
2. El gancho revalidatePage limpia la caché del sitio Next del CMS. Nada cambia en el storefront.
3. El storefront sigue sirviendo la versión vieja hasta un minuto.
4. Nadie avisó, nadie falló, no hay registro de nada.

Un minuto es tolerable para una página de contenido. Deja de serlo cuando el editor quiere ver el resultado de lo que acaba de publicar, o cuando lo que se corrige es un precio, una condición o un texto equivocado, y hay que mirar el reloj.

Hacia dónde ir

Esbozo, no decisión. Son tres piezas y ya hay media hecha.

1. Etiquetar las lecturas. Las lecturas del storefront a Payload pasan todas por src/lib/payload.ts: alcanza con agregar next: { tags: [...] } en un solo lugar, con una etiqueta por entidad y otra por página concreta.
2. Un punto de entrada en el storefront. Una ruta que reciba qué se publicó y revalide esas etiquetas, protegida por un secreto compartido. REVALIDATE_SECRET ya está declarada para eso; habría que generar un valor propio por entorno, porque hoy es el marcador de posición del starter y es el mismo en los tres.
3. Un gancho en el CMS que la llame. afterChange en las colecciones que el storefront consume, con el mismo criterio que ya usa revalidatePage.

Dos detalles de Next 16, que es la versión del storefront, para no perder tiempo después:

• revalidateTag ahora lleva dos argumentos: la etiqueta y el perfil de caché (revalidateTag('pagina:ofertas', 'max')).
• updateTag, que es lo que el storefront usa después de cada mutación del carrito, solo puede llamarse dentro de una Server Action. En una ruta que recibe un aviso externo no sirve.

Puntos abiertos

• Qué entidades avisan. Páginas seguro. ¿También menús, cabecera, pie, etiquetas de producto? Cada una tiene su propio ritmo de cambio.
• Qué hacer si el aviso falla. El storefront puede estar caído o la red cortada. La revalidación por tiempo queda como red de seguridad, así que el peor caso es volver a lo de hoy; conviene que el gancho no rompa el guardado en el CMS por eso.
• Borradores y vista previa. La vista previa ya tiene su propio camino (Live Preview) y no debería mezclarse con esto.
• Más de una instancia del storefront. Si en algún momento corre replicado, una revalidación alcanza solo a la instancia que recibió el aviso. Hoy no aplica; conviene anotarlo.
• Rotación del secreto y de dónde sale la dirección del storefront en el entorno del CMS.

Qué no hace falta decidir ahora

Nada de esto bloquea a RF-009 ni a ningún requisito en curso. La consecuencia de no hacerlo es conocida y acotada: hasta un minuto de demora entre publicar y ver. Vale la pena resolverlo por sí mismo, en su propia historia, no de apuro dentro de otra.