Skip to content

BB Cache

BB Cache is a WordPress performance plugin by Brightbase. It combines a file-based page cache with a set of HTML optimisers and, since 0.3.0, a Cloudflare integration. Everything runs on the site's own server: no remote service, no telemetry.

This documentation describes version 0.3.0.

The pieces

Piece Code What it does
Page cache drop-in advanced-cache.tpl.php, inc/serve.php Serves a stored HTML file before WordPress loads, or records why it could not (the X-BB-Cache header).
Page cache store and purge inc/class-page-cache.php Writes the final HTML of cacheable responses to disk and removes it when content changes.
Output buffer inc/class-html.php Owns the single output buffer. Every optimiser is a filter on bb_cache_html_output.
File optimisation inc/class-minify.php Combines Google Fonts requests, minifies and combines same-origin CSS and JS.
JavaScript inc/class-js.php Adds defer; delays scripts until the first interaction.
Media inc/class-media.php Lazy loading for images and iframes, YouTube click-to-play preview, optional image dimensions.
Boost inc/class-boost.php Critical CSS with async stylesheets, local Google Fonts, WebP swap, LCP preload, srcset, lazy videos, preconnect, HTML minify, content-visibility.
Preload inc/class-preload.php Resource hints, hover prefetch, cache warming from the sitemap.
Cloudflare inc/class-cloudflare.php Mirrors page-cache purges to the zone and sets the Cache-Control headers the edge acts on.
Heartbeat inc/class-heartbeat.php Reduces or disables the Heartbeat API per context.
Install inc/class-install.php Drop-in, WP_CACHE, .htaccess block, health checks, conflict detection.
Settings inc/class-settings.php One option (bb_cache_settings), defaults, sanitisation, and the generated config.php.
Admin inc/class-admin.php Settings → BB Cache, the admin-bar menu, notices and tools.
WP-CLI inc/class-cli.php The wp bb-cache commands.

How they fit together

request
  │
  ▼
[.htaccess block, optional]  cached file exists → Apache sends it, PHP never starts   X-BB-Cache: HIT (htaccess)
  │
  ▼
wp-content/advanced-cache.php → inc/serve.php → cache/bb-cache/config.php
  │   cached file exists → sent, PHP exits                                             X-BB-Cache: HIT
  │   otherwise the reason is recorded                                                 X-BB-Cache: MISS (reason)
  ▼
WordPress renders the page inside one output buffer
  │
  ▼
bb_cache_html_output filters, in priority order
   10  file optimisation   (Google Fonts combine, CSS, JS)
   20  JavaScript          (delay, defer)
   30  media               (lazy load, YouTube preview, dimensions)
   35  boost               (fonts, critical CSS, srcset, WebP, videos, LCP, preconnect, content-visibility, HTML minify)
   40  preload             (hints, hover prefetch script)
 1000  page cache          (edge headers, then store the result on disk)

Content changes purge the affected files. Each purge fires the bb_cache_purged action, which the Varnish and Cloudflare mirrors listen to. Cache preload refills the cache from the sitemap, either daily or after a full purge.

What is on by default

A fresh install has these settings on: page cache (10 hour lifespan), separate mobile cache, CSS minify and combine, Google Fonts combine, JS minify, hover prefetch, Heartbeat reduced to every 2 minutes in all three contexts, and WordPress emoji script removal. Every other feature is off.

Several list defaults were written for the site the plugin was built for. They are marked in the settings reference; review them before relying on them.

Where to go next