Cloudflare Workers SEO

TL;DR — Cloudflare Workers are little programs that run on Cloudflare’s network, in front of your real website. A Worker can add a redirect, fix a meta tag, or inject a canonical tag as the page flies past — without touching your CMS or waiting on developers. This page is the hands-on, code-level version of the broader Edge SEO idea: how you actually do it on Workers specifically. The one rule you can’t break: whatever a Worker changes, it has to change for Google and real visitors the same way. Showing Google something different is cloaking.

What a Cloudflare Worker is, in plain terms

If your site is on Cloudflare, every request from a visitor (or from Googlebot) passes through Cloudflare’s network before it reaches your actual server. A Worker is a small script you can run at that point in the path. It sees the request coming in and the response going out, and it can change either one. Evidence for this claim Cloudflare Workers run code on Cloudflare's network and can inspect or modify requests and responses. Scope: Cloudflare Workers request handling. Confidence: high · Verified: 2026-07-14 Cloudflare Workers: How Workers works

That’s the whole appeal for SEO: you get to fix things on pages you can’t otherwise edit. Stuck on a locked-down platform? Waiting weeks for a developer to add a canonical tag? A Worker can do it in minutes, live, without a deploy to the site itself.

What people use Workers for in SEO

• Redirects — send old URLs to new ones at the edge, even thousands of them.
• Fixing or adding tags — inject a canonical tag, correct a title, add hreflang, drop in structured data — all without editing the page’s source.
• Rewriting headers — add or fix things like X-Robots-Tag.

The rule you cannot break

Whatever your Worker does, it has to do it for everyone. If you show Googlebot a different page than a real person sees — to game rankings — that’s cloaking, and it’s against Google’s rules. Evidence for this claim Google defines serving materially different content to search engines and users to manipulate rankings as cloaking and a spam-policy violation. Scope: Google Search spam policy; legitimate personalization is context-dependent. Confidence: high · Verified: 2026-07-14 Google: Spam policies — cloaking The safe pattern is simple: apply the same logic to every request, no matter who’s asking. (The Edge SEO hub covers this rule in depth — this page assumes you already get the concept and want the Cloudflare-specific how-to.)

The two ways to hurt yourself

Most “Cloudflare hurt my SEO” stories aren’t the Worker code at all:

1. A bot-blocking setting. Cloudflare’s Bot Fight Mode can accidentally block or challenge Googlebot. If Google can’t fetch your pages, nothing else matters.
2. Caching confusion. Cloudflare has more than one kind of cache, and if you don’t know which one you’re touching, a change you shipped can seem to “not show up.”

Want the actual code — a fetch handler, an HTMLRewriter example, a KV redirect table — plus the caching and bot-blocking details? Switch to the Advanced tab.

TL;DR — A Cloudflare Worker only sees requests matched by its configured route, and it intercepts each one in a single fetch handler, where you do three things in sequence: rewrite the request, rewrite the response headers, and rewrite the response body via HTMLRewriter. That’s the real mechanism behind “inject a canonical” or “fix a title” — and it needs to be idempotent, tested against missing, duplicate, and non-HTML responses, not just the happy path. Redirects at scale live in KV (fast key lookup) or D1 (relational); Bulk Redirects/Rules cover small sets more simply, and I generally prefer edge-level redirects over server-level — but pick one owner per URL, since a Worker redirect, a Bulk Redirect, and an origin redirect can all fire on the same path. Three different things share the word “cache” — the Workers Cache API (caches.default), the Cloudflare edge cache, and origin Cache-Control — and confusing them is the usual cause of “my tag didn’t show up”; diagnose staleness by cache key, layer, TTL, and invalidation rather than guessing. Google’s own ETag / If-None-Match / 304 guidance is directly actionable for a Worker that owns the response. The cloaking line: identical logic for every requester. The most Workers-specific self-inflicted wound is Bot Fight Mode, which runs outside the WAF Ruleset Engine, so ordinary “allow” rules don’t reach it. Ship every SEO-affecting change with recorded version metadata, a tested rollback, and a stop condition — then verify with GSC URL Inspection and CF-Cache-Status.

What this article is (and isn’t)

This is the practitioner, code-level companion to the Edge SEO hub. The hub owns the general definition, the platform comparison table (Workers, Akamai, Fastly, Lambda@Edge, Vercel, Netlify), the Snippets-vs-Workers decision, and the full treatment of the cloaking rule. I’m not re-deriving any of that here. This page goes one level deeper into Cloudflare Workers specifically — the runtime this very site’s own worker runs on, wired in through run_worker_first in wrangler.toml — with real APIs rather than “edge compute can inject tags” hand-waving.

A note before the code: Google has no Cloudflare-Workers-specific documentation. The official guidance that governs this (cloaking policy, HTTP caching, CDN crawling) is general and applies to any edge implementation. I’d rather say that plainly than imply a Google doc exists that doesn’t.

How a Worker sits in the request/response path

A Worker is a serverless script running on V8 isolates. Every request it’s routed to enters through a fetch handler. Evidence for this claim A Cloudflare Worker receives HTTP requests through a fetch handler. Scope: Cloudflare Workers handlers. Confidence: high · Verified: 2026-07-14 Cloudflare Workers: Fetch handler “Routed to” is doing real work in that sentence: a Worker only sees requests that match its configured route or custom domain — everything else never reaches the fetch handler at all. Where two routes could both match the same URL, the more specific pattern takes precedence, so before you trust a Worker’s behavior for a given URL, confirm the route actually matches it and check which deployed version is live on that route (Wrangler environments and gradual rollouts mean the version serving traffic isn’t always the one in your editor). Inside the handler you can do three distinct things, in order:

1. Rewrite the request before it goes to your origin.
2. Rewrite the response headers on the way back out.
3. Rewrite the response body — via HTMLRewriter.

Here’s the minimal shape:

export default {
  async fetch(request, env, ctx) {
    // 1. (optionally) inspect/modify the request
    const response = await fetch(request);   // hit the origin

    // 2. rewrite headers
    const headers = new Headers(response.headers);
    headers.set("X-Robots-Tag", "index, follow");

    // 3. rewrite the body with HTMLRewriter (see next section)
    return new Response(response.body, { ...response, headers });
  },
};

The SALT.agency team, who coined “edge SEO” off Cloudflare Workers research, built their tooling as a filter chain — a request filter, a response filter, and a body filter. That’s the same three-phase pattern; they just named it. Keeping those three phases separate in your head keeps a Worker legible.

Rewriting HTML with HTMLRewriter

HTMLRewriter is Cloudflare’s streaming HTML parser, and it’s the actual API behind every “inject a tag” trick. Evidence for this claim Cloudflare HTMLRewriter provides selector-based handlers that can transform streamed HTML elements. Scope: Cloudflare Workers HTMLRewriter API. Confidence: high · Verified: 2026-07-14 Cloudflare Workers: HTMLRewriter You register .on(selector, handler) element handlers, and the handler gets getAttribute / setAttribute, prepend / append, setInnerContent, and replace. Because it streams, you’re not buffering the whole document in memory.

Injecting or fixing a canonical tag

class CanonicalHandler {
  constructor(url) { this.url = url; }
  element(el) { el.setAttribute("href", this.url); }
}

const rewriter = new HTMLRewriter()
  .on('link[rel="canonical"]', new CanonicalHandler("https://example.com/preferred/"));

return rewriter.transform(response);

If the page has no canonical at all, you attach a handler to head and append one instead of editing an existing tag. Either way, remember the lesson from the canonicalization side of this: rel=canonical is a hint, not a command — a Worker lets you set it consistently across a whole platform, but Google still decides.

The CanonicalHandler above assumes a tag already exists and the response is HTML. Neither is guaranteed in production, and getting it wrong is how you end up with two canonical tags on one page instead of one. Before you ship a rewrite like this, make it idempotent and test it against:

• No existing canonical — your handler needs to detect the missing case and append one to head, not silently no-op on link[rel="canonical"] matching nothing.
• A duplicate or malformed canonical already present — decide whether you remove the stray tag or leave your rewrite to add a second one (the latter is a real bug, not an edge case — duplicate canonicals are a common self-inflicted issue).
• A non-HTML response — an API route, an image, or a redirect response passed through the same Worker shouldn’t be run through HTMLRewriter at all; scope the transform to routes and content types you’ve actually checked.
• Running the transform twice on the same response (a retry, a nested fetch) — confirm it doesn’t re-append a second tag.

Adding or correcting hreflang alternates

Same mechanism, driven off config. You append one link[rel="alternate"] per locale to head. If your alternates are per-locale and relational, that config belongs in D1; if it’s a flat lookup, KV is fine. The point is that HTMLRewriter injects them identically for every requester — you’re not branching on user agent.

Injecting JSON-LD structured data

new HTMLRewriter().on("head", {
  element(head) {
    head.append(
      `<script type="application/ld+json">${JSON.stringify(schema)}</script>`,
      { html: true }
    );
  },
});

CPU limits that bite at scale

One competitor claim I’d push back on is “sub-millisecond, no constraints.” The real ceiling is CPU time: 10 ms on the free plan, 30 ms on paid (wall-clock time waiting on fetch doesn’t count — CPU time does). For typical rewrites you’ll never notice. For heavy HTMLRewriter passes over very large pages, it’s a real constraint to design around, not scaremongering.

Redirects at the edge: KV vs D1 vs Rules

I typically prefer to have redirects on the edge (CDN level) over having them on the server — it offloads the work from your origin and applies before the page is ever generated. On Cloudflare specifically, in my Ahrefs guide to redirects for SEO I laid out that you’ve got several options: single or bulk redirects, redirect rules, page rules, or Workers with key-value pairs — or a Worker that modifies headers to add a redirect.

For a Worker-driven table, KV is the natural home: a fast, eventually-consistent key lookup keyed by URL.

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const target = await env.REDIRECTS.get(url.pathname);   // KV namespace
    if (target) return Response.redirect(target, 301);
    return fetch(request);
  },
};

Reach for D1 when redirects are relational (per-locale, per-segment SQL you want to query). And know when a Worker is overkill: for a small, static set of redirects, Cloudflare’s Bulk Redirects or Redirect Rules are simpler and need no code at all. Don’t hand-roll a KV Worker for fifty redirects.

Pick one owner for a given URL and don’t let a Worker redirect, a Bulk Redirect, a Redirect Rule, and an origin redirect all apply to the same path — they’re separate systems that can each fire on the same request, and when more than one matches, you’re debugging precedence instead of a clean redirect. Before you add a redirect anywhere, check whether one already exists for that path in the other systems, and pick the layer based on match complexity (simple 1:1 vs. pattern-based), scale, and who needs to observe or roll it back — a Worker redirect lives in your code and logs; a Bulk Redirect or Rule lives in the dashboard and is easier for a non-developer to audit or revert.

Caching: three different things, one confusing name

This is the section competitor pages skip, and it’s the one that generates the most “why didn’t my change show up” confusion. Three separate layers share the word cache:

• The Workers Cache API — caches.default and caches.open(). This is a Worker-scoped programmable cache you read and write in code.
• The Cloudflare edge cache — the CDN cache that serves your assets. Distinct from the Cache API.
• Origin Cache-Control — the headers your origin (or your Worker) sets, which influence both of the above and what Googlebot does.

Conflate them and you’ll swear a change didn’t deploy when it’s just being served from a layer you didn’t purge.

When a change genuinely isn’t showing up, don’t guess — diagnose it layer by layer:

1. Cache key. What request attributes determine whether two requests hit the same cached entry (URL, and sometimes headers or cookies if your cache key includes them)? A rewrite that varies by something not in the cache key can serve the wrong variant.
2. Which layer served the response. Check CF-Cache-Status (HIT/MISS/EXPIRED/DYNAMIC) to see whether the edge cache answered at all, or the request reached your Worker.
3. Location/state. Cloudflare’s cache is distributed across data centers — a purge or a fresh deploy doesn’t necessarily invalidate every edge location instantly.
4. TTL and the rule that set it. Confirm whether a cache rule, a Cache-Control header from your origin, or a header your Worker itself set is controlling the TTL.
5. Invalidation. Did you purge the specific URL, purge everything, or rely on TTL expiry? A Worker-owned Cache API entry (caches.default) needs its own explicit delete() — purging the CDN cache doesn’t touch it.

What Googlebot does with ETag / If-None-Match / 304

If your Worker generates or rewrites the response, it owns the caching headers — which means Google’s December 2024 HTTP caching guidance is directly actionable for you. Google supports heuristic HTTP caching through ETag/If-None-Match and Last-Modified/If-Modified-Since, strongly recommends ETag because it’s less error-prone, and says that when the crawler’s ETag matches, your server should return a 304 Not Modified with no body. A response-generating Worker can implement exactly that: compute an ETag, compare it against If-None-Match, and short-circuit to a 304 itself — saving compute and giving Googlebot a fast, cacheable signal.

The max-age recrawl tradeoff

Google also says to consider setting Cache-Control: max-age to help crawlers decide when to recrawl. The catch for a Worker that rewrites HTML: an aggressive max-age on a page whose Worker-injected tags just changed can delay Googlebot from seeing the update you just shipped. Don’t slap a long cache lifetime on rewritten HTML and forget about it.

The cloaking boundary, applied to Workers

The hard rule, in Workers terms: run the same logic for every requester. Google’s spam policy defines cloaking as presenting different content to users and search engines to manipulate rankings, and specifically calls out inserting text or keywords only when the requester is a search engine.

A couple of clarifications, because people over-correct here:

• Inspecting the User-Agent isn’t automatically cloaking. Logging bot traffic, or serving a cached response faster to any client, is fine. The line is a content difference by requester identity, done to manipulate rankings.
• Page-split A/B testing on Workers is fine. Splitting users by URL and treating every requester the same is legitimate. Splitting by who’s asking — bot vs. human — is not.

A worked example of the safe pattern: this site’s own preview gate is a Worker that 404s any /preview/ path unless a cookie matches a secret. It returns that 404 to everyone without the cookie — Googlebot included. That’s precisely the safe shape: it isn’t hiding one thing from bots and showing another to users; it applies one rule uniformly.

And don’t lean on a bot-only pre-render step even if you build it cleanly on Workers. Google has called dynamic rendering a workaround and not a long-term solution; a Worker that pre-renders only for bots inherits that deprecation.

How a Worker can accidentally block or slow Googlebot

This is the most Workers-specific way to shoot yourself in the foot, and it’s usually not in your Worker code.

Bot Fight Mode runs outside the Ruleset Engine

Bot Fight Mode (and Super Bot Fight Mode) can produce false positives against legitimate crawlers, Googlebot included. The trap: Bot Fight Mode is evaluated on a separate pipeline from the WAF Ruleset Engine, so your ordinary WAF “allow” or “skip” custom rules don’t override it. If Bot Fight Mode is challenging Googlebot, you don’t fix it with an allow-rule — you have to change or disable the mode itself. (Confirm the current mechanics against Cloudflare’s Bot Fight Mode and Super Bot Fight Mode docs before you rely on it — bot products change.)

The verified-bots custom rule pattern

Cloudflare exposes a cf.client.bot field and a verified-bots allow pattern so you can permit known-good crawlers in your custom rules — useful for the WAF side, though (per above) it does not reach Bot Fight Mode.

The CDN itself is neutral-to-positive

To be clear about the myth: Cloudflare-the-CDN doesn’t hurt SEO. Google’s own 2024 Crawling December work notes that Google increases crawl rate when it detects a CDN — but that a CDN can also accidentally block Googlebot via WAF/bot rules, and that a 503 is better than a bot-verification interstitial. The risk is a misconfigured Worker or bot setting, not the infrastructure.

Verifying what Googlebot actually received

After any Worker deploy, confirm what a crawler actually got — don’t assume:

• GSC URL Inspection → Test Live URL. Fetches the page as Google and shows the rendered HTML, so you can confirm your injected canonical/hreflang/JSON-LD is actually present.
• Check CF-Cache-Status alongside the HTML. HIT / MISS / EXPIRED tells you whether you’re looking at a fresh Worker response or a cached one — the fastest way to catch a “change didn’t show up” that’s really a cache-layer issue.
• Fetch as Googlebot directly. Request with Googlebot’s user agent and compare — but remember matching the string proves nothing about identity; verify real Googlebot with reverse + forward DNS against Google’s published ranges (see the Scripts tab).

Deployment hygiene specific to Workers

A successful wrangler deploy tells you the script shipped — it doesn’t tell you Googlebot is getting the right rendered output. Treat every SEO-affecting Worker change as a release with a record, not just a push:

• Scope your routes. Don’t run a Worker on /* by default. Match it to the paths it needs in your wrangler.toml route patterns so a bug can’t take down your whole site.
• Check current limits before you promise scale. CPU time, subrequest counts, and script size limits vary by plan and change over time — confirm against Cloudflare’s current limits page before you design a rewrite around a specific ceiling, rather than relying on a remembered number.
• Record version metadata for the release. Cloudflare’s versions and deployments model tracks the source version, compatibility date, bindings, and routes for each deploy — note which version is live on which route so a “the Worker is doing X” claim is checkable against what’s actually deployed, not what’s in your editor.
• Version and roll back with Wrangler environments. Ship to a staging environment, gradually roll out by percentage, and keep the ability to revert to the prior version instantly.
• Use scoped logs to monitor the rollout — with their limits in mind. Cloudflare’s Workers Logs and log tailing can support debugging a gradual rollout, but logs are sampled and retained for a limited window — treat them as scoped evidence for the requests they captured, not a complete record of every crawler visit.
• Set a stop condition and test the rollback before you need it. Decide up front what observed behavior (error rate, a wrong response on a spot-check, a crawl-rate drop) halts the rollout, and confirm the rollback path actually works rather than assuming it will.
• Purge cache as part of the deploy. Since three cache layers are in play, make cache purge/invalidation an explicit step of shipping a rewrite, not an afterthought.

A Bing note, and one forward-looking thing

Bing has no Cloudflare/edge-specific guidance either. But because a Worker deploy is instant while crawls aren’t, IndexNow is the natural pairing — fire it the moment a Worker-driven redirect table or tag change ships so Bing (and other participating engines) re-crawl promptly. And worth a glance: Cloudflare shipped edge-enforced canonicalization as a product feature (“Redirects for AI Training”) — verified AI-training crawlers get a 301 to your canonical URL with one toggle. It’s a useful contrast to hand-rolling canonical logic in your own Worker, and a reminder that “serving crawlers something different from users” is a pattern Microsoft has publicly been skeptical of on Cloudflare’s other AI-crawler features — a good gut check on any bot-conditional Worker.

For the broader picture — the platform comparison, Snippets vs. Workers, the dev-queue and governance angles — head back to the Edge SEO hub.

AI summary

A condensed take on the Advanced version:

• Cloudflare Workers SEO = doing technical SEO on Cloudflare’s V8-isolate runtime. It’s the code-level, Workers-specific implementation of the general Edge SEO concept — see that hub for the definition, platform comparison, and cloaking depth.
• A Worker only sees what its route matches. Route/domain configuration and precedence decide which requests reach the fetch handler at all — confirm the route and the deployed version before trusting a Worker’s behavior for a URL.
• One fetch handler, three phases: rewrite the request, rewrite the response headers, rewrite the response body. Body rewriting runs through HTMLRewriter — the real mechanism for injecting a canonical, fixing hreflang, or adding JSON-LD. Make the rewrite idempotent and test it against missing, duplicate, malformed, and non-HTML responses, not just the happy path.
• Redirects: KV for fast key lookups, D1 for relational config, Bulk Redirects/Rules for small static sets. Patrick prefers edge-level redirects over server-level — but pick one owner per URL; a Worker redirect, Bulk Redirect, Redirect Rule, and origin redirect can all fire on the same path.
• Three caches share one word: the Workers Cache API (caches.default), the Cloudflare edge cache, and origin Cache-Control — conflating them causes “my change didn’t show up.” Diagnose it by cache key, layer, TTL, and invalidation rather than guessing.
• Google’s ETag/If-None-Match/304 caching guidance (Dec 2024) is directly actionable: a response-owning Worker can short-circuit to a 304 itself; but an aggressive max-age can delay recrawl of a just-changed page.
• Cloaking rule: identical logic for every requester. Inspecting the UA isn’t automatically cloaking; a content difference by requester identity to manipulate rankings is.
• Biggest self-inflicted risk: Bot Fight Mode runs outside the WAF Ruleset Engine, so normal allow-rules don’t reach it — you must change the mode itself.
• Ship deliberately: check current plan limits before promising scale, record version metadata (compatibility date, bindings, routes) per release, use scoped logs (sampled, not a complete record) to watch a rollout, and set a stop condition with a tested rollback before you need it.
• Verify with GSC URL Inspection (Test Live URL) and the CF-Cache-Status header; watch CPU limits (10 ms free / 30 ms paid) on heavy rewrites.

Official documentation

There is no Cloudflare-Workers-specific SEO doc from Google or Bing — the governing guidance is general. The most useful primary sources are split between the search engines (policy/caching) and Cloudflare (the runtime APIs).

Google (applies to any edge implementation)

• Spam policies — cloaking — the hard boundary any Worker logic must respect.
• Crawling December: HTTP caching (2024) — ETag / If-None-Match / 304 / max-age, directly actionable for a response-owning Worker.
• Crawling December: CDNs and crawling (2024) — how a CDN affects crawl rate and how bot rules can block Googlebot.
• Dynamic rendering (deprecated) — why a bot-only pre-render Worker inherits a deprecated pattern.
• Overview of Google crawlers and fetchers — user agents and published IP ranges for verification.

Cloudflare (the runtime)

• HTMLRewriter — the streaming HTML parser API.
• Cache API — caches.default / caches.open().
• How the cache works — the Cache API vs. the edge cache.
• Routes and domains — route matching, precedence, and which requests actually invoke a Worker.
• Bulk Redirects — the no-code redirect system a Worker redirect can conflict or overlap with.
• Workers limits — current CPU, subrequest, and script-size ceilings; plan- and date-sensitive, so check it directly rather than trusting a remembered number.
• Versions and deployments — versioned/gradual deploys and rollback.
• Workers Logs — invocation logs, tailing, and their sampling/retention limits.
• Bot Fight Mode / Super Bot Fight Mode — the bot settings that can block Googlebot.
• Allow traffic from verified bots — the cf.client.bot custom-rule pattern.

Bing — no edge/Workers page exists; IndexNow is the relevant pairing for instant post-deploy re-crawl.

Quotes from the source

On-the-record statements. Each Google link is a deep link that jumps to the quoted passage.

Google — the cloaking boundary

• “Cloaking refers to the practice of presenting different content to users and search engines with the intent to manipulate search rankings and mislead users.” — Google Search Central, Spam policies for Google web search. Jump to quote
• “Inserting text or keywords into a page only when the user agent that is requesting the page is a search engine, not a human visitor” — listed as an example of cloaking. Jump to quote

Google — HTTP caching (Crawling December, 2024)

• “Google’s crawling infrastructure supports heuristic HTTP caching as defined by the HTTP caching standard, specifically through the ETag response- and If-None-Match request header, and the Last-Modified response- and If-Modified-Since request header.” Jump to quote
• “We strongly recommend using ETag because it’s less prone to errors and mistakes (the value is not structured unlike the Last-Modified value).” Jump to quote
• “If the ETag value sent by the crawler matches the current value the server generated, your server should return an HTTP 304 (Not modified) status code with no HTTP body.” Jump to quote
• “While not required, consider also setting the max-age field of the Cache-Control header to help crawlers determine when to recrawl the specific URL.” Jump to quote

Google — dynamic rendering (deprecated)

• “Dynamic rendering was a workaround and not a long-term solution for problems with JavaScript-generated content in search engines.” Jump to quote

Me — on edge-level redirects

• “I typically prefer to have redirects on the edge (CDN-level) over having them on the server.” — from my Ahrefs guide, 11 Types of Redirects & Their SEO Impact. Relayed from my own published article; wording is mine but confirm the exact phrasing against the live page before treating it as a hard quote.

Cloudflare / SALT.agency — why Workers for redirects

• “we needed to implement simple redirects, which should be easy to create on the majority of platforms but wasn’t supported” — Igor Krestov & Dan Taylor, Diving into Technical SEO using Cloudflare Workers (Cloudflare blog). Relayed via summarization of the Cloudflare blog post, not confirmed as an exact substring — re-verify against the live page before using as a hard blockquote.

Which tool for the job?

“I need to add redirects.”

• A small, static set (a few dozen, no logic)? → Cloudflare Bulk Redirects or Redirect Rules. No Worker, no code.
• Thousands of URL-keyed redirects? → A Worker + KV lookup.
• Relational (per-locale, per-segment, queried) redirects? → A Worker + D1.
• Need to redirect and rewrite headers in the same pass? → A Worker (Rules can’t do both).

“I need to inject or fix a tag (canonical, hreflang, title, JSON-LD).”

• → A Worker with HTMLRewriter. There’s no no-code Cloudflare product for arbitrary body rewriting; this is Workers’ job.

“Googlebot’s crawl dropped after I added Cloudflare.”

• First suspect Bot Fight Mode / Super Bot Fight Mode, not your Worker. Check whether it’s challenging Googlebot — and remember a WAF allow-rule won’t fix it; you change the mode itself.
• Then check WAF custom rules and whether a 503/interstitial is being served to bots.
• Only then audit the Worker code and route scope.

“My injected tag isn’t showing up.”

• Check CF-Cache-Status. HIT/EXPIRED? You’re seeing a cached response — purge the right layer (Workers Cache API vs. edge cache) and re-test.
• MISS and still wrong? Now it’s your Worker logic or route scope. Confirm with GSC URL Inspection.

“Should I pre-render only for bots on a Worker?”

• → No. That’s dynamic rendering, which Google has deprecated. Prefer SSR/static rendering applied to everyone.

Cloudflare Workers SEO checklist

Before you ship a rewrite Worker

• Route is scoped to the paths it needs in wrangler.toml — not /* by reflex — and you’ve confirmed which deployed version is actually live on that route.
• The Worker applies identical logic to every requester (no bot-vs-human content branch).
• HTMLRewriter handlers are idempotent and tested against a missing tag, a duplicate/malformed existing tag, and a non-HTML response — not just the happy path.
• For redirects, you’ve picked the right tool: Bulk Redirects/Rules (small/static), KV (URL-keyed at scale), or D1 (relational) — and confirmed no other redirect system already owns that URL.
• Current plan limits (CPU, subrequests, script size) were checked directly, not remembered.
• Cache-Control on rewritten HTML isn’t so aggressive it delays recrawl of changed pages.
• Version metadata (compatibility date, bindings, routes) is recorded for the release, with a tested rollback path and a defined stop condition for the rollout.

Caching sanity

• You know which of the three layers (Workers Cache API / edge cache / origin Cache-Control) you’re touching.
• If the Worker owns the response, it sets a correct ETag and can short-circuit to 304.
• Cache purge/invalidation is an explicit step in the deploy.

Bot access

• Bot Fight Mode / Super Bot Fight Mode isn’t challenging Googlebot (checked directly — a WAF allow-rule does not override it).
• Verified-bots custom rule (cf.client.bot) is in place if you gate on the WAF side.
• Bots get a 503, not a verification interstitial, when you need to slow them.

Verify after deploy

• GSC URL Inspection → Test Live URL confirms the injected tag is in the rendered HTML.
• CF-Cache-Status checked (HIT/MISS/EXPIRED) so you know if you’re seeing a cached copy.
• IndexNow fired (Bing/others) if a redirect table or tag change just shipped.
• Versioned via Wrangler environments with a tested rollback path.

The mental models

1. One handler, three phases. Every Worker is a fetch handler, and everything you do lives in one of three phases in order: rewrite the request → rewrite the response headers → rewrite the response body (HTMLRewriter). Locate what you’re changing in that sequence before you write a line.

2. “Cache” is three things, not one. Workers Cache API (caches.default) ≠ Cloudflare edge cache ≠ origin Cache-Control. When a change “doesn’t show up,” ask which layer you’re actually looking at before you touch the code.

3. The cloaking test: identity vs. logic. Branching on who’s asking to change content = cloaking. Applying the same logic to everyone — even if that logic inspects the UA for logging or speed — is fine. Ask: “would a real user get exactly what Googlebot got?”

4. The blame order for a crawl drop. Bot Fight Mode → WAF rules → Worker code → route scope. The bot settings run on a pipeline your allow rules don’t reach, so suspect them first.

5. The Worker owns the response — so it owns caching semantics. If your Worker generates or rewrites the body, it’s responsible for ETag, 304, and max-age. That’s a capability (short-circuit a 304 yourself) and a liability (over-cache and delay recrawl).

Cloudflare Workers SEO — cheat sheet

Pick the redirect tool

The three caches

HTMLRewriter handler API

• getAttribute / setAttribute — read/set a tag attribute (e.g., canonical href)
• prepend / append — add markup inside an element (e.g., a tag into head)
• setInnerContent — replace an element’s contents
• replace — swap the element entirely

Fast facts

• CPU limit: 10 ms free / 30 ms paid (wall-clock fetch waits don’t count).
• Cloaking = content difference by requester identity to manipulate rankings — not “the Worker read the UA.”
• Bot Fight Mode runs outside the WAF Ruleset Engine — allow-rules don’t reach it; change the mode.
• Verify a Worker change: GSC Test Live URL + CF-Cache-Status header.
• Google recommends ETag; matching ETag → return 304 with no body.

Verify what Googlebot actually got — after a Worker deploy

Fetch as Googlebot and diff (shell)

# Fetch as a normal browser
curl -sS -A "Mozilla/5.0" https://example.com/page/ -o user.html -D user.headers

# Fetch as Googlebot's UA
curl -sS -A "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" \
  https://example.com/page/ -o bot.html -D bot.headers

# The bodies should be identical — a diff is a cloaking red flag
diff user.html bot.html && echo "identical (good)"

# Check what cache layer served it
grep -i "cf-cache-status" bot.headers   # HIT / MISS / EXPIRED

Confirm real Googlebot (UA strings are trivially spoofed) — reverse + forward DNS

# 1) Reverse DNS the IP from your logs — must end in googlebot.com / google.com
host 66.249.66.1
# 2) Forward DNS that hostname back — must resolve to the same IP
host crawl-66-249-66-1.googlebot.com

If either check fails, it isn’t Googlebot. You can also match against Google’s published googlebot.json ranges.

Read the injected tags out of the rendered HTML (DevTools console)

// Paste into the browser console on the live page to confirm your Worker's injection
[...document.querySelectorAll('link[rel="canonical"]')].map(l => l.href);
[...document.querySelectorAll('link[rel="alternate"][hreflang]')]
  .map(l => `${l.hreflang} -> ${l.href}`);
[...document.querySelectorAll('script[type="application/ld+json"]')].map(s => s.textContent);

A minimal ETag / 304 short-circuit inside a Worker

export default {
  async fetch(request, env, ctx) {
    const res = await fetch(request);
    const body = await res.text();
    const etag = `"${await sha1(body)}"`;               // your hash of choice
    if (request.headers.get("If-None-Match") === etag) {
      return new Response(null, { status: 304 });        // no body, per Google's guidance
    }
    const headers = new Headers(res.headers);
    headers.set("ETag", etag);
    return new Response(body, { ...res, headers });
  },
};

Tools for building and verifying Workers SEO

• Wrangler — Cloudflare’s CLI for developing, versioning, and deploying Workers (route scoping, environments, rollback, secrets). This is where deployment hygiene lives.
• HTMLRewriter — the built-in streaming HTML parser; the API for all body rewriting.
• Workers KV / D1 — the storage for redirect tables and config (KV for key lookups, D1 for SQL).
• GSC URL Inspection → Test Live URL — fetches and renders the page as Google so you can confirm an injected canonical/hreflang/JSON-LD actually landed.
• CF-Cache-Status header (via curl -I or DevTools Network) — tells you HIT/MISS/EXPIRED so you know whether you’re looking at a cached copy or a fresh Worker response.
• IndexNow — ping Bing and other participating engines the instant a Worker-driven change ships.
• Server log analysis — the ground truth for whether real (verified) Googlebot is reaching your Worker’s routes at all.

Audit a Worker for SEO consistency and cache behavior

Review this Cloudflare Worker fetch handler as an SEO edge change. Trace the request,
response-header, body-rewrite, redirect, and caching paths. Return:
1. Every branch based on user agent, bot status, cookie, geography, or request header
2. Whether Googlebot/no-cookie traffic can receive different indexable content or SEO tags
3. HTMLRewriter selectors that fail when a tag is missing or create duplicates
4. Redirect lookups that can chain, loop, or fall through unexpectedly
5. Each use of the Cache API, Cloudflare edge cache behavior, and origin Cache-Control—kept as separate layers
6. Cache keys that could mix variants or preserve a stale canonical/robots/header change
7. A minimal test matrix for users, verified bots, cache hit/miss, and representative URLs

Apply the same content and SEO logic to bots and users. Flag intentional personalization
for human review rather than calling it cloaking automatically. Do not invent Cloudflare
settings, bindings, routes, cache rules, or origin behavior that are not in my input.

Worker code, bindings, routes, and relevant cache/security configuration:
[PASTE INPUT]

Review an HTMLRewriter change before deployment

Audit this HTMLRewriter implementation for one SEO task: [CANONICAL / HREFLANG / JSON-LD].
Check whether it handles existing, missing, and duplicate elements; produces valid absolute
URLs or JSON; applies to the intended route cohort; and behaves identically for every
requester. Then return corrected code plus raw-response and rendered-response tests.

Do not add product, organization, locale, URL, or schema facts that are not supplied.

Code and expected per-route output:
[PASTE INPUT]

Test yourself: Cloudflare Workers SEO

Five quick questions on doing technical SEO with Cloudflare Workers. Pick an answer for each, then check.

Resources worth your time

My related writing

• 11 Types of Redirects & Their SEO Impact (Ahrefs) — the redirect options on Cloudflare, and why I prefer edge-level redirects over server-level.
• The Beginner’s Guide to Technical SEO (Ahrefs) — where edge changes fit in the wider picture.
• JavaScript SEO Issues & Best Practices (Ahrefs) — the rendering side, relevant to any pre-render-on-the-edge temptation.

My speaking

• Fine-Tune your Technical SEO, Page Speed, and Security (Marketing Speak interview) — where I walk through using Cloudflare Workers to rewrite before the user ever sees the page, and offloading redirects to the CDN. Spoken-word interview transcript; treat specific phrasings as paraphrase rather than exact quotes.

From around the industry

• Diving into Technical SEO using Cloudflare Workers — Igor Krestov (SALT.agency) & Dan Taylor on the Cloudflare blog; the origin of the filter-chain (request/response/body) pattern.
• What is edge SEO? (Search Engine Land) — the concept this article’s parent hub covers, in third-party form.
• Edge SEO (Dan Taylor) — from the person who coined the term off Cloudflare Workers research.
• HTMLRewriter (Cloudflare docs) — the canonical reference for the body-rewriting API.
• How the cache works (Cloudflare docs) — untangles the Cache API from the edge cache.
• Redirects for AI Training (Cloudflare blog) — edge-enforced canonicalization as a product feature, a useful contrast to hand-rolling it in a Worker.

Go deeper / sideways

• Edge SEO — the parent hub: general concept, platform comparison, Snippets vs. Workers, the cloaking rule in full.

Cloudflare Workers SEO

Cloudflare Workers SEO is using Cloudflare's serverless V8-isolate runtime — the fetch handler, the HTMLRewriter streaming parser, KV/D1 storage, and the Cache API — to make technical SEO changes (redirects, header and meta-tag rewriting, canonical/hreflang/structured-data injection) at the CDN edge, before a response reaches Googlebot or a user, without deploying to the origin or CMS.

Related: Edge SEO, Canonicalization

Cloudflare Workers SEO

Cloudflare Workers SEO is the practice of using Cloudflare Workers — a serverless runtime built on V8 isolates — to apply technical SEO changes at the CDN edge instead of at the origin server or CMS. It’s the most common concrete implementation of the broader edge SEO idea, because Workers is the most mature and widely adopted serverless edge platform for this use case.

Every request a Worker sees enters through a single fetch handler, and inside it you can do three things in sequence: rewrite the request, rewrite the response headers, and rewrite the response body. Body rewriting — injecting a canonical tag, correcting hreflang, adding JSON-LD, fixing a title — runs through HTMLRewriter, Cloudflare’s streaming HTML parser. Redirects at scale usually live in KV (fast key lookups) or D1 (relational config), and the Workers Cache API (caches.default) is a distinct layer from the Cloudflare edge cache and from origin Cache-Control headers.

The one hard rule is cloaking: whatever a Worker does, it must do identically for Googlebot and real users — you can’t serve different content by requester identity to manipulate rankings. The most Workers-specific way to hurt yourself isn’t the Worker code at all; it’s Bot Fight Mode or a misconfigured WAF rule silently blocking or slowing Googlebot before your Worker logic even runs. For the general concept, the cloaking rule, and the cross-platform comparison, see the Edge SEO hub; this term covers the Workers-specific mechanics.

Related: Edge SEO, Canonicalization

Changelog