Description
This plugin is the control panel for ModPageSpeed — a web server optimization module for nginx and Apache. ModPageSpeed must be installed and running on your server for this plugin to function. It is not a standalone caching plugin.
The plugin does three things:
- Enables full-page caching — adds
Cache-Control: public, max-age=Nto anonymous page responses (WordPress does not send this by default), with explicit bypasses for logged-in users, WooCommerce cart/checkout/account pages, search, feeds, and 404s. - Keeps the cache fresh — calls the ModPageSpeed purge API when you publish, update, or delete content, when comments change, when stock levels change, and when terms or theme settings change.
- Gives you control in WP Admin and WP-CLI — per-post-type TTLs, cookie bypass list, excluded URL patterns, a first-run setup wizard, and
wp pagespeed flush|status|test-connectioncommands.
Works with both mod_pagespeed deployments (auto-detected), with one important difference:
- The mod_pagespeed optimizer worker (the Docker / nginx reverse proxy) caches full HTML pages itself — the plugin’s headers and purge calls drive its page cache directly.
- The mod_pagespeed module (the native web-server module for Apache, nginx, and IIS) does not cache HTML (it is a streaming rewriter; its in-place optimization caches only images, CSS, and JS). Full-page caching with the module requires an external cache layer in front (nginx
proxy_cache, Varnish, or a CDN) plusModifyCachingHeaders offorDownstreamCachePurgeLocationPrefix— with the module’s defaultModifyCachingHeaders on, it replaces this plugin’s Cache-Control header on rewritten HTML. With the module, the plugin’s purge calls evict optimized sub-resources and metadata, not HTML pages.
Server requirements
- The mod_pagespeed module (v1.15.0+r3 or later) or the mod_pagespeed optimizer worker (v2.0.0 or later) installed on your web server.
- For the optimizer worker: its management API enabled (
--api-port). - For the module: an admin handler with
EnableCachePurge on. - For full logged-in-user correctness an nginx cookie-bypass map block is required — the setup wizard provides a copy-paste snippet and verifies it.
WP-CLI
wp pagespeed flush [--url=<url>]— purge the home page (and posts page), or one specific URL on this site.wp pagespeed status— detected product, version, license tier, purge prerequisites, and last-purge status.wp pagespeed test-connection— verify the admin API is reachable and correctly configured (read-only, never purges).
License
This plugin is free software, licensed under the GNU General Public License v2.0 or later. The full GPL-2.0 license text is bundled with the plugin in the LICENSE file.
Third Party Services
This plugin makes HTTP requests to the operator-configured ModPageSpeed admin API URL. Data sent includes page URLs (for cache purging) and an API key (for authentication). No data is sent to We-Amp or any third party.
Installation
- Install ModPageSpeed on your server (see https://modpagespeed.com/).
- Install and activate this plugin.
- Follow the setup wizard under Settings > ModPageSpeed: detect your server, enter the admin API URL, test the connection, apply the nginx.conf snippet, enable caching, and run a test purge.
FAQ
Does this plugin cache pages itself?
No. Caching happens server-side: in the mod_pagespeed optimizer worker itself, or — with the mod_pagespeed module — in your front cache (proxy_cache, Varnish, or CDN; the module does not cache HTML, see the Description). The plugin only sets cache headers and sends purge requests — the same architecture as other server-layer cache plugins.
I run the mod_pagespeed module on Apache or nginx — do I get full-page caching?
Not from the module alone. The module never caches HTML; put an external cache (nginx proxy_cache, Varnish, or a CDN) in front of it and set ModifyCachingHeaders off (or use DownstreamCachePurgeLocationPrefix) so this plugin’s Cache-Control headers reach that cache. The plugin’s purge calls to the module evict optimized sub-resources and metadata.
Does it work without ModPageSpeed installed?
No. The setup wizard will guide you to the server module installation docs if no server is detected.
Screenshots





Changelog
0.1.1
- Fix: cache purges work again on mod_pagespeed modules 1.17.0 and later (including 2.x), which accept a purge only as a POST request.
- Fix: when the admin URL of the mod_pagespeed module uses a different host name than the site (for example 127.0.0.1), the plugin now explains why the module refuses the purge (“URL belongs to another host”) and how to fix it: use the site’s own host name in the admin URL, or the global admin handler (pagespeed_global_admin). Test connection and the setup wizard warn about it up front. Repeated purge errors are shown once.
- Changed: an admin URL on the site’s own host name (the recommended setup for the mod_pagespeed module) no longer shows the “not a loopback address” warning or a red status item; a neutral reminder to restrict the unauthenticated endpoint at the web server is shown instead.
- Changed: the settings page, setup wizard and WP-CLI name the two servers “mod_pagespeed module” and “mod_pagespeed optimizer worker”. The Product row of
wp pagespeed statusshows these names instead of 1.1 and 2.0.
0.1.0
- Initial release: Cache-Control headers for anonymous pages, purge on publish/update/delete/comment/stock changes, ModPageSpeed 1.1 and 2.0 support with auto-detection, setup wizard, WP-CLI commands.
