Flx Modernize plugin

Version 1.0.0 · WordPress 6.0+ (tested to 7.1) · PHP 7.4+ · GPL-2.0-or-later

Flx Modernize is the WordPress side of Flx. For each eligible request it builds the page data, sends it to your Flx Render service in a signed request, and sends the visitor the HTML that comes back. If anything goes wrong, it steps aside and WordPress renders the page as usual.

How a request is handled

1. Eligibility. The request must be an anonymous visitor's GET or HEAD request for an HTML page (not a feed, embed, robots.txt, favicon or trackback). Logged-in users always get normal WordPress.
2. Filter. flx_modernize_should_render can turn Flx off for the request. It can never turn it on for a request that failed step 1.
3. Route. The plugin recognises the blog home page, category and tag archives, single posts, pages, search results and the 404 page. Anything else stays WordPress.
4. Content checks. Previews, drafts, private and scheduled content and any post with a password stay WordPress. A password-protected post is never sent, even to a visitor who has entered the password.
5. Page data. The payload is built as the anonymous visitor (user 0), so content filters and dynamic blocks never see a user. See Flx Render for the fields.
6. Render. The payload goes to the Render service (5-second timeout). On success the HTML is sent with Cache-Control: private, no-store; a 404 keeps its 404 status.
7. Fallback. On any failure (timeout, error, invalid response) WordPress renders the page and it is sent with Cache-Control: no-store.

Both rendered and fallback responses also define DONOTCACHEPAGE, so page-cache plugins don't store them. If output has already started before the plugin runs, it stays out of the way, because the cache headers could no longer be sent.

Install and configure

1. Install Flx Modernize from wordpress.org and activate it. Until a Render URL is saved it sends nothing anywhere.
2. Have a Flx Render service for your theme: run the package yourself, or have it hosted for you.
3. Generate a signing key and add it to wp-config.php (recommended; see Signing).
4. In wp-admin, open Flx Modernize, enter the Render service URL, and save.
5. Check it: open the site in a private window. The page HTML links …/static/styles.css on your Render service domain and the response has Cache-Control: private, no-store.

Settings

Constants win over options. Keep the secret in wp-config.php, which is not readable by other site users.

Signing

With a key ID and secret configured, every request to the Render service carries five headers: X-Flx-Render-Protocol, -Key-Id, -Timestamp, -Nonce and -Signature. The signature is a lowercase hex HMAC-SHA256 of a canonical string built from the method, path, query, timestamp, nonce and a hash of the body.

On the Render service, set the same pair as FLX_RENDER_SIGNING_KEYS=keyId:secret and FLX_RENDER_AUTH_MODE=enforce. It then rejects unsigned requests, unknown keys, bad signatures, replayed nonces and timestamps more than 300 seconds off, all with HTTP 401. Use one key per site.

Generate a secret with openssl rand -hex 32.

REST endpoints

The Render service fetches the site's theme CSS from these public, read-only endpoints. They serve CSS that any visitor's browser could already see.

If your CDN or firewall challenges automated traffic (Cloudflare's Bot Fight Mode, for example), allow the Render service to reach these endpoints, or pages render without the theme CSS.

The filter

// Keep a landing page on normal WordPress.
add_filter( 'flx_modernize_should_render', function ( $should_render ) {
	return is_page( 'campaign' ) ? false : $should_render;
} );

Return false to keep WordPress for the request. Only a literal true keeps Flx on.

Menus

The header menu comes from the theme header's Navigation block. Custom, page, post and category links are supported, one level deep. Page and post links with an ID use the item's current permalink and are dropped if the item is not published.

Rollback

Deactivate the plugin. Every visitor gets normal WordPress immediately; nothing else changes.

Known limits in 1.0.0

• Twenty Twenty-Five only.
• No comments on Flx post pages.
• Logged-in visitors always see normal WordPress.
• Sub-menus are not supported.
• Post lists show each post's excerpt; the theme shows the full post.
• No public HTML caching; every Flx page is private, no-store.