Next WP

The Next.js Revalidation plugin automates the process of updating your headless Next.js frontend whenever content changes in WordPress.

Supported Triggers:

• Modification (add, update, delete) of posts, pages, categories, tags, authors, or media.
• Support for custom post types and taxonomies.

Capabilities:

• Automatic Revalidation: Triggered by content changes.
• Manual Revalidation: Option to trigger a full site refresh.
• Admin Notifications: Optional visibility into revalidation events within WordPress.

The plugin automates the cache invalidation process through the following lifecycle:

1. Trigger: When content (posts, pages, categories, tags, or media) is created, updated, or deleted in WordPress, the plugin sends a webhook to your Next.js API route.
2. Payload: The webhook includes the content type and the specific ID of the affected content.
3. Validation: Your Next.js API route validates the request using the WORDPRESS_WEBHOOK_SECRET.
4. Revalidation: Upon successful validation, Next.js revalidates the appropriate cache tags, causing the site to fetch fresh content for the affected pages.

Next WP uses Next.js cache tags to ensure that when content changes in WordPress, only the affected pages are revalidated.

Manual Setup (Non-Railway)

1. Install Plugin: Download next-revalidate.zip from the latest releases and upload it to your WordPress site.
2. Configure Settings: In WordPress, navigate to Settings → Next.js Revalidation.
3. Set URL: Enter your Next.js site URL.
4. Set Secret: Enter the same WORDPRESS_WEBHOOK_SECRET value used in your Next.js .env.local file.

To get a local development environment running, follow these steps:

1. Clone the repository
2. Install dependencies using pnpm (recommended)
3. Set up environment variables by copying the example file to .env.local and configuring your WordPress credentials.
4. Start the development server.

Your site will be available at http://localhost:3000.

# Clone the repository
git clone https://github.com/9d8dev/next-wp.git
cd next-wp

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your WordPress URL and credentials

# Start development server
pnpm dev

The WordPress plugin works by sending webhooks to your Next.js site. For revalidation to succeed, your Next.js application must implement an API endpoint at /api/revalidate capable of processing the incoming webhook payloads and verifying the webhook secret.

Security Note: The webhook secret configured in the WordPress plugin is used to secure this endpoint, ensuring that only your WordPress instance can trigger cache revalidations.

Before installing, ensure your environment meets these requirements:

• Node.js: version 18.17 or later.
• pnpm: version 8.0 or later (recommended), though npm or yarn are supported.
• WordPress: A site with the REST API enabled (standard in WordPress 4.7+).

To deploy the frontend to Vercel:

1. Click the Deploy with Vercel button.
2. Provide the following environment variables during setup:
   • WORDPRESS_URL: Your existing WordPress site URL.
   • WORDPRESS_HOSTNAME: Your WordPress domain (for image optimization).
   • WORDPRESS_WEBHOOK_SECRET: A secure random string.
3. Once deployed, you must manually install the next-revalidate plugin on your WordPress site and configure it with your Vercel deployment URL and the secret you generated.

Railway provides a one-click deployment for the full stack: MySQL + WordPress + Next.js. The template includes a custom WordPress Docker image with the next-revalidate plugin pre-installed and the nextjs-headless theme active.

Deployment Steps

1. Click the Deploy on Railway button in the repository.
2. Wait for MySQL, WordPress, and Next.js services to deploy.
3. Visit the WordPress URL to complete the standard WordPress installation wizard.

Post-Deployment Configuration

1. WordPress Admin: Go to Settings → Next.js Revalidation.
2. Next.js URL: Enter your deployed Next.js public URL.
3. Webhook Secret: Copy the WORDPRESS_WEBHOOK_SECRET from your Next.js service variables in Railway and paste it into the WordPress plugin settings.
4. Save settings.

To install the plugin in your WordPress environment, follow these steps:

1. Upload the next-revalidate.zip file via the WordPress admin plugin installer, OR extract the next-revalidate folder directly into your /wp-content/plugins/ directory.
2. Activate the plugin through the WordPress admin interface.
3. Navigate to Settings > Next.js Revalidation to begin configuration.

Revalidation requires matching configurations in both WordPress and your Next.js application.

1. WordPress Plugin Settings

In your WordPress admin dashboard:

1. Go to Settings > Next.js Revalidation.
2. Enter your Next.js site URL (ensure there is no trailing slash).
3. Create a secure webhook secret (a random string). You can generate one using openssl rand -base64 32.
4. Save your settings.

2. Next.js Environment Variables

Add the exact same secret to your Next.js environment variables (e.g., in .env.local) so the API route can validate incoming webhooks.

# .env.local
WORDPRESS_WEBHOOK_SECRET="your-secret-key-here"

To use this plugin, follow these steps:

1. Upload the next-revalidate folder to your WordPress /wp-content/plugins/ directory.
2. Activate the plugin via the 'Plugins' menu in your WordPress admin dashboard.
3. Navigate to Settings > Next.js Revalidation to complete the setup.

The project requires a .env.local file in the root directory with the following keys to connect to your WordPress instance and handle cache revalidation:

• WORDPRESS_URL: The full URL of your WordPress site (e.g., https://your-wordpress-site.com).
• WORDPRESS_HOSTNAME: The domain name used for image optimization in Next.js (e.g., your-wordpress-site.com).
• WORDPRESS_WEBHOOK_SECRET: A secure random string used to authenticate cache revalidation webhooks.

WORDPRESS_URL="https://your-wordpress-site.com"
WORDPRESS_HOSTNAME="your-wordpress-site.com"
WORDPRESS_WEBHOOK_SECRET="your-secret-key-here"