StaticQ Headless

StaticQ Headless turns WordPress into the CMS behind a Cloudflare-hosted Astro frontend. Editors keep the familiar WordPress admin; visitors get static-fast pages served from Cloudflare’s edge and a durable R2 cache; and the plugin keeps both sides in sync automatically, without a full rebuild, a cron job, or a manual cache purge on every edit.

When you publish, update, unpublish, or reschedule a post, the plugin works out exactly which URLs changed (the post’s permalink, the archives and paginated archives it appears on, the relevant feeds, and the sitemap) and refreshes only those. Nothing else is touched, so a single edit never invalidates your whole site.

Important: everything the plugin does runs against your own Cloudflare and GitHub accounts, using credentials you provide. StaticQ Headless does not send your content or credentials to any StaticQ-operated server. There is no telemetry and no phone-home. See External services below.

What it does

• Per-URL cache invalidation. On each editorial change the plugin computes the impacted URL set with a dedicated URL-impact engine (post, home archive, term archives with correct pagination, author archive, feeds, sitemap) and dispatches just those URLs to a small Cloudflare Worker you deploy from the setup wizard (the “receiver”). The receiver is what purges Cloudflare’s edge cache for those URLs, or drops the stored copy in R2 so the frontend re-renders it on the next request. WordPress only ever sends the list of changed URLs, so your WordPress install never needs Cloudflare cache-purge permissions.
• Two-layer edge delivery. The Astro frontend serves pages from Cloudflare’s edge cache backed by a durable R2 store, so pages stay fast even after the edge cache evicts them, and cold renders are smoothed out.
• Managed Astro frontend deploy. From wp-admin you connect a GitHub repository (or create a new private one, generated from the public StaticQ Astro starter template so GitHub populates it server-side, with no local git binary and nothing written to your WordPress server), provisions the Cloudflare Worker and R2 bucket, syncs the GitHub Actions variables and secrets, and triggers the deploy. From then on, editing the frontend is a normal git push.
• REST “speed layer” for Astro. Batched-query REST endpoints under /wp-json/sqheadless/v1/ (site config, homepage, archive, single, SEO head, sitemap) collapse WordPress’s _embed N+1 fan-out into a handful of SQL queries, for much faster SSR on media-heavy archives. The frontend uses them automatically and falls back to standard WordPress REST when they are absent.
• Cache warmup. Prime the edge cache by enumerating every archive and post URL and dispatching them ahead of your visitors.
• Rendered-content cache (optional). Persists rendered post HTML on the WordPress side and re-renders only when the post changes, smoothing cold-render spikes on shortcode- and gallery-heavy content.
• SEO-plugin aware. If Rank Math or Yoast is active, the frontend uses that plugin’s own <head> and structured data; breadcrumb schema is filled in when your SEO plugin does not emit it. No SEO plugin required.
• Built-in tutorials. Step-by-step guides ship inside the plugin under StaticQ Headless → Tutorials, always matching your installed version, including how to bring your own Astro templates into the deploy pipeline.
• Extensible. A documented action and a set of filters let you add URLs to the refresh set, register custom pages, or observe every editorial event. A Refresh Simulator dry-runs the engine with your hooks so you can see exactly what an edit would invalidate.

Bring your own Astro templates

The StaticQ Astro starter (the repository the wizard generates into your GitHub account) is a starting point, not a straitjacket. Replace its pages and components with your own design and deploy through the same managed pipeline (connect your repository and push). The one requirement is that your project keeps the plugin’s caching contract that the starter ships with (the edge/R2 middleware, the cache-key module, and the WordPress data client), so per-URL invalidation keeps working. The built-in Tutorials cover exactly what to keep.

External services

StaticQ Headless connects to external services only when you ask it to (during setup and deploy actions in wp-admin, and when your content changes), and only to accounts and endpoints you configure. It never contacts a StaticQ-operated service, and it sends no analytics.

A note on bundled code: the receiver Worker the plugin uploads to your Cloudflare account ships inside the plugin as a small prebuilt bundle (assets/worker/dist.js, ~13 KB). Its full human-readable TypeScript source ships right next to it in assets/worker/src/, with build instructions and an integrity hash in assets/worker/README.md.

1. Cloudflare API (https://api.cloudflare.com).
Used when you configure and deploy the Cloudflare side from the Setup tab and the Astro Setup wizard (all admin-triggered, never on the front end and never automatically). Using the Cloudflare API token, account ID, and zone ID you enter, the plugin creates and updates the receiver Worker (uploading its bundled script), provisions the frontend Worker and an R2 bucket, sets Worker variables and secrets, manages the workers.dev subdomain, and binds a custom domain. This is your own Cloudflare account. Cloudflare terms: https://www.cloudflare.com/website-terms/ (privacy policy: https://www.cloudflare.com/privacypolicy/).

2. GitHub API (https://api.github.com).
Used when you set up and deploy the Astro frontend (the Astro Setup wizard), and only when you trigger those actions. Using a GitHub personal access token you provide, the plugin verifies or creates a repository (a new one is created by generating it from the public StaticQ Astro starter template at https://github.com/daixtech/staticq-headless-starter, which GitHub copies into your account server-side), sets GitHub Actions variables and (libsodium-encrypted) secrets, and dispatches and monitors the deploy workflow. This is your own GitHub account. GitHub terms: https://docs.github.com/site-policy/github-terms/github-terms-of-service (privacy statement: https://docs.github.com/site-policy/privacy-policies/github-privacy-statement).

3. Your receiver endpoint (a URL you configure).
When content changes (and when you use the manual refresh or warmup tools), the plugin POSTs to the URL you set, normally the Cloudflare Worker you deployed above. The request contains the list of changed absolute URLs plus basic post metadata (event type, post ID, post type) and your site’s home_url(), signed with an HMAC secret for authenticity. No API tokens or account IDs are ever sent to this endpoint. Because the URL is yours, its terms are yours.