Skip to main content

FlatWP WordPress Connector

The FlatWP WordPress Connector is a modern React-powered plugin that bridges WordPress with your Next.js frontend. It provides real-time monitoring, cache management, webhooks for on-demand revalidation, and a beautiful admin dashboard.

Features​

  • Modern React Dashboard - Built with React 18, TypeScript, and Vite
  • Real-time Monitoring - Connection status, cache stats, performance metrics
  • Cache Management - Clear cache by type, path, or all at once
  • Activity Logs - Track all plugin activities
  • Settings Management - Full configuration through a modern UI
  • Webhook Automation - Automatic content revalidation on WordPress changes
  • Preview Mode - Preview draft content in your Next.js site
  • Menu Support - Custom menu fields for icons and badges

Installation​

Download from GitHub Releases (Recommended)​

  1. Go to GitHub Releases
  2. Download flatwp-wordpress-connector-{version}.zip
  3. In WordPress Admin, go to Plugins → Add New → Upload Plugin
  4. Upload the ZIP file and click Install Now
  5. Click Activate Plugin

Using the Starter Download Script​

If you're using the FlatWP Starter template:

pnpm run download-plugin

This downloads the latest plugin version to your project folder.

Requirements​

  • WordPress 6.0 or higher
  • PHP 7.4 or higher (8.1+ recommended)
  • WPGraphQL plugin installed and activated

Initial Configuration​

Step 1: Access the Plugin​

After activation, you'll see FlatWP in your WordPress admin menu. Click it to open the dashboard.

Step 2: Configure Connection Settings​

Navigate to the Settings tab and configure:

SettingDescriptionExample
Next.js URLYour Next.js frontend URLhttps://your-site.com or http://localhost:3010
Revalidation SecretShared secret for webhook authenticationAuto-generated or your FLATWP_SECRET
Preview SecretSecret for draft content previewSame as revalidation secret
Generate Secure Secrets

Click the "Generate" button next to secret fields to create cryptographically secure random strings. Copy these to your Next.js .env.local file.

Step 3: Enable Webhooks​

In the Settings tab:

  1. Enable the Webhooks toggle
  2. Configure webhook options:
    • Revalidation Delay: Milliseconds to wait before sending webhook (default: 1000)
    • Timeout: Maximum wait time for webhook response (default: 10000)
    • Concurrent Webhooks: Maximum simultaneous webhook requests (default: 3)

Step 4: Test Connection​

  1. Return to the Dashboard tab
  2. Click Test Connection
  3. Look for a green "Connected" status indicator with response time

Dashboard Overview​

The FlatWP dashboard provides real-time insights into your headless WordPress setup.

Connection Status​

  • Connected (green) - Next.js site is reachable and responding
  • Disconnected (red) - Cannot reach Next.js site
  • Response Time - Latency in milliseconds

Cache Statistics​

  • Cache Hit Rate - Percentage of requests served from cache
  • Total Requests - Number of cache operations
  • Last Cleared - Timestamp of last cache clear operation

Content Statistics​

  • Total Posts - Published post count
  • Total Pages - Published page count
  • Drafts - Unpublished content count

System Status​

  • PHP Version - Current PHP version
  • WordPress Version - Current WordPress version
  • Active Plugins - Number of active plugins

Cache Management​

Navigate to FlatWP → Cache to manage your Next.js cache.

Clear Cache Options​

ActionDescription
Clear AllPurges entire Next.js cache
Clear HomepageRevalidates only the homepage
Clear PostsRevalidates all blog posts
Clear PagesRevalidates all pages
Clear Specific PathRevalidate a specific URL path

Clear Specific Path​

To clear a specific page:

  1. Enter the path (e.g., /about or /blog/my-post)
  2. Click Clear Path
  3. Check the confirmation message

Activity Logs​

The Activity Logs tab shows all plugin activities:

  • Cache Operations - Clear events with timestamps
  • Connection Events - Test results and status changes
  • Settings Changes - Configuration updates
  • Webhook Activity - Sent webhooks and responses

Filtering Logs​

Use the filter dropdown to show:

  • All activities
  • Cache operations only
  • Settings changes only
  • Connection events only

REST API Endpoints​

The plugin exposes REST API endpoints under /wp-json/flatwp/v1/:

Dashboard​

GET /wp-json/flatwp/v1/dashboard/stats

Returns all dashboard statistics.

Connection​

GET /wp-json/flatwp/v1/connection/status
POST /wp-json/flatwp/v1/connection/test

Cache​

GET /wp-json/flatwp/v1/cache/stats
POST /wp-json/flatwp/v1/cache/clear
POST /wp-json/flatwp/v1/cache/clear-path

Clear cache parameters:

{
  "type": "all" | "homepage" | "posts" | "pages"
}

Clear path parameters:

{
  "path": "/about"
}

Settings​

GET /wp-json/flatwp/v1/settings
PUT /wp-json/flatwp/v1/settings

Activity Logs​

GET /wp-json/flatwp/v1/logs?page=1&per_page=20&type=all

Menu Icons and Badges​

FlatWP adds custom fields to WordPress menu items for icons and badges.

Available Fields​

FieldDescriptionExample
flatwp_iconLucide icon namerocket, home, settings
flatwp_badgeBadge textNew, Beta, Pro

Setting Icons via WP-CLI​

# Add icon to menu item
wp post meta update <MENU_ITEM_ID> flatwp_icon "rocket"

# Add badge to menu item
wp post meta update <MENU_ITEM_ID> flatwp_badge "New"

Querying via GraphQL​

query GetMenuWithIcons {
  menus(where: { location: PRIMARY_NAV }) {
    nodes {
      menuItems {
        nodes {
          id
          label
          uri
          flatwpIcon
          flatwpBadge
        }
      }
    }
  }
}

Popular Icon Names​

Browse all icons at lucide.dev/icons

Navigation: home, menu, search, chevron-down, chevron-right

Actions: plus, check, edit, trash-2, download, upload

Business: briefcase, building-2, users, dollar-sign

Development: code-2, github, git-branch, terminal, database

Preview Mode​

The plugin enables draft content preview in your Next.js site.

Configuration​

In Settings, configure:

  • Preview URL Pattern - How preview URLs are constructed
  • Token Expiration - How long preview tokens remain valid

How It Works​

  1. Click "Preview" on a draft post in WordPress
  2. Plugin generates a secure preview token
  3. Redirects to your Next.js site with the token
  4. Next.js validates the token and displays draft content

Webhook Events​

The plugin sends webhooks to Next.js when content changes:

EventTriggerRevalidated Paths
post_publishedPost is publishedPost URL, homepage, archives
post_updatedPost is modifiedPost URL
post_deletedPost is trashedPost URL, homepage, archives
page_publishedPage is publishedPage URL
page_updatedPage is modifiedPage URL

Webhook Payload​

{
  "event": "post_published",
  "post_id": 123,
  "post_type": "post",
  "paths": ["/blog/my-post", "/", "/blog"],
  "timestamp": 1702659600,
  "secret": "your-shared-secret"
}

Troubleshooting​

"Your theme does not support navigation menus"​

The plugin automatically adds menu support. If you still see this:

  1. Deactivate and reactivate the plugin
  2. Clear WordPress object cache
  3. The plugin adds add_theme_support('menus') automatically

Connection Test Fails​

Possible causes:

  1. Next.js URL is incorrect
  2. API secret doesn't match
  3. Next.js revalidation route not configured
  4. CORS issues

Debug steps:

  1. Verify Next.js is running
  2. Check environment variables match in both places
  3. Check browser console for errors
  4. Review WordPress error logs

React Admin Not Loading​

  1. Ensure the plugin is the release version (not source code)
  2. Check browser console for JavaScript errors
  3. Verify WordPress REST API is accessible
  4. Clear browser cache

Webhooks Not Triggering​

  1. Verify webhooks are enabled in Settings
  2. Check that secrets match between WordPress and Next.js
  3. Look at Activity Logs for webhook failures
  4. Verify Next.js revalidation endpoint exists (/api/revalidate)

GraphQL Queries Return Null for Icons/Badges​

  1. Verify FlatWP plugin is activated
  2. Check that WPGraphQL is installed
  3. Test in GraphiQL (WordPress Admin → GraphQL → GraphiQL)
  4. Ensure menu item post meta is set correctly

Security​

The plugin implements multiple security measures:

  • Nonce Verification - All API requests verified with WordPress nonces
  • Capability Checks - manage_options capability required
  • Input Sanitization - All inputs sanitized before processing
  • Output Escaping - All outputs escaped before rendering
  • Secure Secrets - Cryptographically secure random generation

Performance​

The React admin is optimized for performance:

  • Code Splitting - Route-based lazy loading
  • React Query - Efficient data fetching and caching
  • Optimized Build - Vite production optimization
  • Tree Shaking - Unused code eliminated

See Also​