Cómo la Caché en Hashnode GraphQL Retrasa la Actualización de tu Blog Headless

Aquí tienes una propuesta de artículo técnico, estructurado para ser informativo, directo y ofrecer soluciones prácticas. Está diseñado para un blog de desarrollo o tecnología.

---

La Trampa de la Caché en Hashnode GraphQL: Por qué tu Blog Headless Tarda Días en Actualizarse

Acabas de terminar un nuevo artículo en tu dashboard de Hashnode. Corriges un error tipográfico en el último minuto, le das al botón de "Publicar" y corres a tu sitio web personalizado (creado con Next.js, Astro o Remix) para verlo en vivo.

Refrescas la página. Nada. Esperas 5 minutos. Nada. Haces un nuevo deploy de tu frontend. Sigue sin aparecer.

Bienvenido a "La Trampa de la Caché de Hashnode".

Si estás utilizando Hashnode como un CMS Headless, es probable que te hayas topado con este muro. No es que tu código esté mal, y no es que Next.js (o tu framework de elección) esté fallando en su revalidación. El problema reside en una capa invisible que a menudo ignoramos: la agresiva estrategia de caché de la API de Hashnode.

En este artículo, desglosaremos por qué ocurre esto y, lo más importante, cómo solucionarlo definitivamente.

El Diagnóstico: No eres tú, es el Edge

Para entender el problema, debemos entender la prioridad de Hashnode. Como plataforma de blogging masiva, su prioridad número uno es la velocidad de lectura. Para lograr esto, utilizan una CDN (Content Delivery Network) extremadamente agresiva con sus respuestas GraphQL.

Cuando tu aplicación hace una petición fetch a la API de Hashnode, la solicitud pasa por varias capas:

1. Tu Frontend: (Ej. Next.js ISR).

2. La CDN de Hashnode: (Cloudflare/Fastly, etc.).

3. La Base de Datos de Hashnode.

El problema surge cuando configuras tu frontend para revalidar cada 60 segundos (revalidate: 60), pero la CDN de Hashnode tiene instruido guardar esa respuesta durante horas o hasta que "sienta" que debe purgarse.

Tu servidor le pide datos a la API, pero la API ni siquiera consulta la base de datos; te devuelve la versión "congelada" de hace 2 horas porque es más rápido y barato computacionalmente.

Solución 1: La "Fuerza Bruta" (Headers HTTP)

La forma más rápida de intentar saltarse esta caché es decirle explícitamente a la API que no quieres una versión guardada. Aunque las APIs de GraphQL suelen ser métodos POST (que tradicionalmente no se cachean), muchas infraestructuras modernas sí cachean estas consultas basándose en el cuerpo de la petición.

Puedes intentar forzar una respuesta fresca añadiendo cabeceras estándar de control de caché en tu llamada fetch:

const query = `... tu query graphql ...`;

const response = await fetch('https://gql.hashnode.com', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // Instrucciones para evitar la caché intermedia
    'Cache-Control': 'no-cache, no-store, must-revalidate', 
    'Pragma': 'no-cache',
    'Expires': '0'
  },
  body: JSON.stringify({ query })
});

¿Funciona siempre? No. Algunas CDNs están configuradas para ignorar estas cabeceras si la carga del servidor es alta o según reglas internas de la API pública.

Solución 2: El "Cache Busting" (El truco sucio)

Si las cabeceras no funcionan, puedes engañar a la API haciéndole creer que está recibiendo una petición totalmente nueva y única. Esto se logra inyectando una variable aleatoria o un timestamp en tu consulta GraphQL que no afecte el resultado, pero cambie el "hash" de la petición.

query GetPosts($timestamp: Int!) {
  publication(host: "mi-blog.hashnode.dev") {
    posts(first: 10) {
      title
    }
  }
  # Esta parte no hace nada, pero cambia la firma de la petición
  _dummy: publication(host: "mi-blog.hashnode.dev") { 
     id 
  } 
}

Al enviar un timestamp diferente en cada petición, la CDN no encuentra una copia guardada para esa combinación exacta de caracteres y se ve obligada a ir al servidor original.

Nota: Úsalo con precaución. Esto elimina los beneficios de velocidad de la caché.

Solución 3: La Manera Profesional (On-Demand ISR + Webhooks)

Olvídate de luchar contra la caché en cada petición. La arquitectura correcta para un blog Headless en 2024 no es el polling (preguntar cada X tiempo), sino los eventos.

Hashnode ofrece Webhooks. Puedes configurar Hashnode para que avise a tu servidor cada vez que publicas o actualizas un post.

Paso a paso para usuarios de Next.js (App Router):

1. Crea una ruta de API en tu proyecto (ej: app/api/revalidate/route.ts).

2. Configura el Webhook en Hashnode: Ve al dashboard de tu blog > Webhooks > Add New Webhook. Apúntalo a https://tu-dominio.com/api/revalidate. Selecciona el evento Post Published y Post Updated.

El código de revalidación:

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  // 1. Verificar seguridad (opcional pero recomendado con un secret)
  const secret = request.nextUrl.searchParams.get('secret')
  if (secret !== process.env.MY_SECRET_TOKEN) {
    return NextResponse.json({ message: 'Invalid token' }, { status: 401 })
  }

  // 2. Obtener el slug del cuerpo del webhook
  const payload = await request.json();
  const slug = payload.data?.post?.slug;

  if (slug) {
    // 3. Purgar la caché de Next.js para ese post específico
    // Asegúrate de usar tags en tus fetch: fetch(url, { next: { tags: ['posts'] } })
    revalidateTag('posts'); 
    console.log(`Caché purgada para: ${slug}`);
    return NextResponse.json({ revalidated: true, now: Date.now() })
  }

  return NextResponse.json({ revalidated: false, message: 'No slug found' })
}

Con este método, tu blog es estático (muy rápido) el 99% del tiempo. Pero en el instante exacto en que actualizas en Hashnode, tu web se regenera automáticamente. Sin esperas, sin cachés fantasmas.

Conclusión

La "Trampa de la Caché" de Hashnode es en realidad una característica de optimización que choca con el desarrollo local o las expectativas de actualización inmediata.

No pierdas horas depurando tu código frontend. Si los datos no cambian:

1. Verifica que no estás golpeando la caché del Edge (CDN).

2. Implementa Webhooks y On-Demand Revalidation. Es la única forma robusta de tener un blog headless que se sienta vivo.

---