manifest / integrations / wp-hook-nextjs-revalidate

WP Next.js Revalidate

WordPress plugin to trigger Next.js revalidation via webhooks with custom tags and content types

by John Serrano · github.com/johnsi15/wp-hook-nextjs-revalidate · website

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/johnsi15/wp-hook-nextjs-revalidate/archive/refs/heads/main.zip

No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Readme github.com/johnsi15/wp-hook-nextjs-revalidate ↗

Un plugin de WordPress que permite disparar webhooks de revalidación para Next.js 15 con soporte para cache tags y paths específicos.

🚀 Características

✅ Revalidación automática de cache en Next.js cuando se actualiza contenido en WordPress
✅ Soporte para tags y paths específicos de Next.js 15
✅ Filtros por tipo de contenido (posts, páginas, custom post types)
✅ Filtros por taxonomías (categorías, etiquetas, taxonomías personalizadas)
✅ Secret key global con opción de override individual
✅ Soporte para HEADLESS_SECRET existente
✅ Función de testing integrada
✅ Interfaz de administración intuitiva

📋 Requisitos

WordPress 5.0 o superior
PHP 7.4 o superior
Next.js 15 con App Router

🔧 Instalación

Descarga el plugin

git clone https://github.com/johnsi15/wp-nextjs-revalidate.git

Sube a WordPress
- Sube el archivo wp-nextjs-revalidate.php a /wp-content/plugins/
- O comprime en ZIP y sube desde el panel de WordPress
Activa el plugin
- Ve a Plugins > Plugins instalados
- Activa "WP Next.js Revalidate"
Configura el plugin
- Ve a Configuración > Next.js Revalidate
- Configura tu secret key global
- Añade tus webhooks

⚙️ Configuración

1. Secret Key Global

Puedes usar tu HEADLESS_SECRET existente o configurar uno nuevo:

Opción A: Usar HEADLESS_SECRET existente (Recomendado)

// En tu wp-config.php
define('HEADLESS_SECRET', 'tu-secret-key-aqui');

Opción B: Configurar en el plugin

Ve a Configuración > Next.js Revalidate
Introduce tu secret key en "Global Secret Key"
Guarda los cambios

2. Configurar tu API de Revalidate en Next.js

Crea tu API route en Next.js:

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

export async function PUT(request: NextRequest) {
  const requestBody = await request.text()
  const { paths, tags } = requestBody
    ? JSON.parse(requestBody)
    : { paths: [], tags: [] }
  let revalidated = false

  // Validar secret key
  if (
    request.headers.get('X-Headless-Secret-Key') !== process.env.HEADLESS_SECRET
  ) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 })
  }

  try {
    // Revalidar paths
    if (paths && Array.isArray(paths) && paths.length > 0) {
      await Promise.all(paths.map((path) => revalidatePath(path)))
      console.log('Revalidated paths:', paths)
      revalidated = true
    }

    // Revalidar tags
    if (tags && Array.isArray(tags) && tags.length > 0) {
      await Promise.all(tags.map((tag) => revalidateTag(tag)))
      console.log('Revalidated tags:', tags)
      revalidated = true
    }

    return NextResponse.json({
      revalidated,
      now: Date.now(),
      paths,
      tags,
    })
  } catch (error) {
    console.error('Error revalidating:', error)
    return NextResponse.json(
      { message: 'Error revalidating' },
      { status: 500 }
    )
  }
}

3. Variables de Entorno en Next.js

# .env.local
HEADLESS_SECRET=tu-mismo-secret-que-en-wordpress

🔗 Crear Webhooks

Accede a la configuración
- WordPress Admin > Configuración > Next.js Revalidate
Completa el formulario
- Nombre: Identificador del webhook
- URL: https://tu-sitio.com/api/revalidate
- Secret Key: Déjalo vacío para usar el global
- Tags: posts,categories (separados por coma)
- Paths: /,/blog,/categories (separados por coma)
- Tipos de contenido: Selecciona post, page, etc.
- Taxonomías: Selecciona category, post_tag, etc.
- Eventos: save_post, delete_post, etc.
Prueba el webhook
- Haz clic en "Test Webhook" antes de guardar
- Verifica que recibas una respuesta exitosa

🧪 Testing Local con ngrok

Para probar el plugin desde tu entorno local, puedes usar ngrok:

1. Instalar ngrok

Opción A: Con npm

npm install -g @ngrok/ngrok

Opción B: Descargar desde el sitio

Ve a ngrok.com
Descarga e instala para tu sistema operativo

2. Configurar ngrok

# Regístrate en ngrok.com y obtén tu authtoken
ngrok authtoken TU_AUTHTOKEN_AQUI

3. Exponer tu aplicación local

# Expón tu Next.js local (puerto 3000)
ngrok http 3000

Obtendrás una URL pública temporal como:

https://abc123.ngrok.io

4. Configurar el webhook

En WordPress, usa la URL de ngrok:

https://abc123.ngrok.io/api/revalidate

5. Alternativas a ngrok

LocalTunnel (gratuito)

npm install -g localtunnel
lt --port 3000

Cloudflare Tunnel (gratuito)

# Instalar cloudflared
brew install cloudflare/cloudflare/cloudflared

# Exponer aplicación
cloudflared tunnel --url http://localhost:3000

📚 Ejemplos de Uso

Webhook para Posts

Nombre: Revalidar Posts
URL: https://mi-sitio.com/api/revalidate
Tags: posts,blog
Paths: /,/blog
Tipos de contenido: ✅ Post
Eventos: ✅ Save Post, ✅ Delete Post

Webhook para Categorías

Nombre: Revalidar Categorías  
URL: https://mi-sitio.com/api/revalidate
Tags: categories,navigation
Paths: /categories
Taxonomías: ✅ Category
Eventos: ✅ Created Term, ✅ Edited Term

Webhook para Páginas

Nombre: Revalidar Páginas
URL: https://mi-sitio.com/api/revalidate
Tags: pages
Paths: /
Tipos de contenido: ✅ Page
Eventos: ✅ Save Post

🐛 Solución de Problemas

Error: "Invalid secret"

Verifica que el HEADLESS_SECRET sea el mismo en WordPress y Next.js
Asegúrate de que no haya espacios extra en el secret

Error: "Connection timeout"

Verifica que la URL del webhook sea accesible
Revisa que tu Next.js esté ejecutándose
Para localhost, usa ngrok o similar

Webhook no se dispara

Verifica que hayas seleccionado los tipos de contenido correctos
Asegúrate de que los eventos estén marcados
Revisa los logs de WordPress (wp-content/debug.log)

Ngrok: Error de autenticación

# Verifica tu email en ngrok.com
# Luego configura tu authtoken:
ngrok authtoken TU_AUTHTOKEN

🔧 Desarrollo

Estructura del Plugin

wp-nextjs-revalidate.php    # Plugin principal
├── WPNextJSRevalidate      # Clase principal
├── admin_menu()            # Página de configuración
├── init_webhooks()         # Inicializar webhooks
└── send_webhook()          # Enviar peticiones

Hooks Disponibles

save_post - Guardar post
delete_post - Eliminar post
trash_post - Enviar a papelera
created_term - Crear término
edited_term - Editar término
delete_term - Eliminar término

🤝 Contribuir

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

🙋‍♂️ Autor

John Serrano - @johnsi15

Website: johnserrano.co
LinkedIn: johnsi15

🙏 Agradecimientos

Basado en wp-hook-expose
Inspirado en el ecosistema Faust.js
Documentación de Next.js 15

⭐ Si este plugin te fue útil, ¡considera darle una estrella en GitHub!