Cloudflare APO for WordPress: how it works

What APO is

Most content delivery networks keep copies of the files a page uses: images, style sheets and scripts. They do not keep the page itself, because on WordPress the HTML is built fresh by PHP and can differ from one visitor to the next. A content delivery network (CDN) is a set of servers around the world that keep copies near your visitors; see what is a CDN for the basics.

APO goes one step further. Cloudflare's documentation says it serves your entire WordPress site from Cloudflare's network by caching dynamic content, including the HTML. Cloudflare built it on its Workers platform, which runs code inside its data centers. The Cloudflare plugin for WordPress tells Cloudflare when a page changes, so the saved copy is replaced.

In short, APO is a page cache that lives at the edge of Cloudflare's network instead of on your server. If you already know WordPress caching, it is the page cache layer moved closer to the visitor.

What it changes for a visitor

The main effect is on Time to First Byte (TTFB), the wait before the first byte of the page arrives. Without a page cache, every visit makes WordPress run its code and query the database. With a page cache on the server, the visit still travels all the way to your host. With APO, a cached page is answered from a Cloudflare data center, and your server is not asked at all. Cloudflare's documentation says this aims to make TTFB "both fast and consistent".

A faster first byte moves the other loading times forward too, because nothing else can start before it. First Contentful Paint and Largest Contentful Paint (LCP) both begin after TTFB. See how to fix a slow LCP for how the time splits up.

There are limits, and they matter:

• It does not shrink the page. Heavy images, large scripts and many fonts weigh the same from a nearby server.
• It does not fix taps and clicks. Interaction to Next Paint (INP) depends on the scripts running in the browser, not on where the HTML came from.
• It does not stop layout shifts. Cumulative Layout Shift (CLS) comes from images without sizes, late fonts and injected banners.
• It does little for logged-in visitors. They bypass the cache, so members, editors and shoppers with a cart still wait for your server.

APO also adds two smaller optimizations. Cloudflare says it caches some third-party scripts, and it serves Google Fonts files from your own domain. You can see the font change in the page: the address starts with your domain followed by fonts.gstatic.com.

What APO caches and what it skips

Cloudflare publishes the rules. A response is saved as a page only when all of these are true:

• The request reads a page. The method is GET or HEAD.
• It asks for HTML. The request's Accept header includes text/html, or the header is missing and the address is a page rather than a file.
• Your server answered normally. Status 200 with a Content-Type of text/html.
• The plugin allows it. The cf-edge-cache header from the plugin permits caching.
• No bypass cookie is set. Cookies that start with wp-, wordpress, comment_, woocommerce_, edd_ or jetpack, among others, send the visit to your server.
• The path is not excluded. Checkout pages, wp-cron.php and feeds are never cached.
• The query string is known. Addresses with no query string, or only marketing tags such as utm_source, utm_campaign, gclid and fbclid, are cached. Any other parameter skips the cache.
• No rule says bypass. A Page Rule or Cache Rule set to bypass wins.

When a request misses any rule, it goes to your server and the response shows cf-cache-status: DYNAMIC. The cf-apo-via header says why.

The cookie rule is what keeps private pages safe. A logged-in visitor carries a wordpress_ cookie, and a shopper carries a woocommerce_ cookie once the cart has something in it. Both are sent past the cache, so one person's page is not shown to another.

What you need before you switch it on

The plugin also sets an API token connection between WordPress and your Cloudflare account. Cloudflare's guide uses a ready-made WordPress token template for this. Treat the token like a password: keep it in the plugin settings and nowhere else.

How to switch it on

These are Cloudflare's steps, in order:

1. Check your DNS records in the Cloudflare dashboard, then change your nameservers at your registrar. The change can take up to 24 hours.
2. On the Free plan, go to Speed, then Settings, then Content Optimization, and buy Automatic Platform Optimization for WordPress.
3. In WordPress, install and activate the plugin named Cloudflare.
4. In the Cloudflare dashboard, create an API token from the WordPress template.
5. In the plugin's settings, sign in with your email and the token, apply the recommended settings, and turn Automatic Platform Optimization on.

Cloudflare suggests one more step before you start: run a speed test on your current site. Do that with the same tool and the same pages you will test afterwards, so the before and after numbers compare like with like.

How to check that it works

Three response headers tell you. Cloudflare's documentation gives this test from a terminal. The accept header makes the request look like a browser asking for a page:

curl -svo /dev/null -A "CF" 'https://example.com/' -H 'accept: text/html' 2>&1 | grep 'cf-cache-status\|cf-edge\|cf-apo-via'

Run it twice. The second answer should show:

Then publish a small change to a page and load it again. The plugin should clear the old copy, and the next visit should show your change and, on the visit after, a HIT.

Living with it

A few behaviors surprise people after launch:

• Copies last a long time. Cloudflare says APO keeps cached pages for 30 days and clears a changed page within 30 seconds when the plugin is installed. A page that holds a time-limited token, such as a form with a WordPress security token or a CAPTCHA, can go stale before then. Cloudflare suggests a shorter Edge Cache TTL rule for those pages.
• Your server's cache headers do not decide the edge. APO ignores your server's Cache-Control for its own copy, and it still passes those headers on to the browser. See HTTP caching headers for what the browser does with them.
• Unknown query strings skip the cache. A search page, a filter or a tracking tag that is not on Cloudflare's list goes to your server every time.
• Mobile and desktop can be cached apart. If your theme sends different HTML to phones, switch on Cache by device type. Cloudflare then tells your server the device type in a CF-Device-Type header and keeps one copy per type. Changing this setting clears the cache.
• Your Content-Security-Policy can block the font change. Cloudflare says APO leaves the Google Fonts addresses alone when your policy lacks unsafe-inline for styles and self for fonts. That is a fair trade on a strict site: the page still works, only the font step is skipped.

APO and other caching plugins

Two page caches in a row can serve old pages and make problems hard to trace. Cloudflare recommends turning off caching plugins such as WP Rocket or W3 Total Cache while you set up APO. After APO works, turn them back on one at a time and test whether they help or cause trouble. Clear their caches after APO is active.

Cloudflare lists plugins it supports with APO, including WooCommerce, WP Rocket from version 3.8.6, Redis Object Cache and Object Cache Pro. An object cache is a different layer: it saves database answers inside WordPress, which still helps logged-in visitors and the pages APO skips. The WooCommerce speed guide explains why stores depend on it.

When APO is the wrong tool

• Most visits are logged in. A membership site, a course or a forum sends most traffic past the cache.
• Your host already serves cached pages fast. If your TTFB is already good for visitors far from the server, the gain is smaller. Measure first.
• You cannot move your nameservers. The setup assumes Cloudflare runs your DNS.
• The site is multisite. The plugin does not support it.
• The real problem is in the browser. Large images, heavy scripts and layout shifts need their own fixes. Start with what to fix first.

Mistakes to avoid

• Judging it by a single test. The first request after a change fills the cache. Test twice, and test from more than one place.
• Running two page caches untested. Turn the other cache off first, then add it back only if it helps.
• Forgetting forms and nonces. Give pages with forms a shorter edge lifetime, or test them a day after caching.
• Adding query strings to links. A custom parameter on internal links sends every visit past the cache.
• Expecting it to fix the score alone. It speeds up the first byte. The rest of the page still has to be light.

Check your own page

Run the free audit on your home page and on a busy post. Look at the server response time and at Largest Contentful Paint. If the first byte is slow but the page is light, an edge page cache such as APO is likely to help. If the first byte is already fast, look at images and scripts first.

Sources

• Automatic Platform Optimization: About on Cloudflare Docs: how APO caches HTML, the rules for what it caches, and the Enterprise subdomain limit.
• Activate the Cloudflare WordPress plugin on Cloudflare Docs: plans, plugin compatibility advice, the multisite limit and the setup steps.
• Verify APO works on Cloudflare Docs: the three headers and the test command.
• Query parameters and cached responses on Cloudflare Docs: the allowed parameters and the cookies that bypass the cache.
• APO FAQs on Cloudflare Docs: the 30-day lifetime, purging, origin headers, DevTools and fonts.
• Cloudflare plugin on WordPress.org: what the plugin does and which plans include APO.