HTML Rewriter

Fetch remote HTML pages and analyze or transform them using the HTMLRewriter API. Stream-parse documents at the edge to count elements or inject content without loading a full DOM parser.

API ReferenceCopy Anchor Link

GET /statsCopy Anchor Link

Fetches a page and returns HTML statistics collected via HTMLRewriter handlers.

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/stats?url=https://example.com"

Success ResponseCopy Anchor Link

url string

The requested page URL

title string | null

Text content of the <title> element, if present

linkCount number

Number of <a> elements on the page

imageCount number

Number of <img> elements on the page

headingCounts object

Count of each heading tag (e.g. h1, h2) found on the page

{
  "url": "https://example.com",
  "title": "Example Domain",
  "linkCount": 1,
  "imageCount": 0,
  "headingCounts": { "h1": 1 }
}

Error ResponseCopy Anchor Link

{
  "error": "Missing or invalid query parameter: url",
  "code": "INVALID_URL"
}

Error CodesCopy Anchor Link

• 400 - Missing or invalid url (INVALID_URL)
• 502 - Failed to fetch or analyze the page (FETCH_ERROR)

GET /transformCopy Anchor Link

Fetches a page and injects a banner <div> at the top of <body> using HTMLRewriter.

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/transform?url=https://example.com&banner=Hello%20from%20the%20edge"

Success ResponseCopy Anchor Link

url string

The requested page URL

banner string

The banner text that was injected

html string

The transformed HTML document

{
  "url": "https://example.com",
  "banner": "Transformed by Cloudflare HTMLRewriter at the edge",
  "html": "<html>...</html>"
}

Error ResponseCopy Anchor Link

{
  "error": "Missing or invalid query parameter: url",
  "code": "INVALID_URL"
}

Error CodesCopy Anchor Link

• 400 - Missing or invalid url (INVALID_URL)
• 502 - Failed to fetch or transform the page (FETCH_ERROR)

Use CasesCopy Anchor Link

• Audit page structure (links, images, headings) without a headless browser
• Inject edge banners or notices into proxied HTML responses
• Learn streaming HTML transformation with HTMLRewriter handlers
• Build lightweight HTML analysis tools at the edge

LimitationsCopy Anchor Link

• Static HTML fetch only; JavaScript-rendered content is not executed
• HTML body size is capped before streaming through HTMLRewriter
• Single URL per request; no multi-page crawling
• Fetch timeout on slow origins

Use in your projectCopy Anchor Link

import { MAX_HTML_BYTES } from "../constants/defaults";export async function fetchHtml(url: string): Promise<string> {  const res = await fetch(url, {    headers: { "User-Agent": "cloudflare-experiments/html-rewriter" },    redirect: "follow",  });  if (!res.ok) {    throw new Error(`Upstream returned HTTP ${res.status}`);  }  const contentType = res.headers.get("content-type") ?? "";  if (!contentType.includes("text/html") && !contentType.includes("application/xhtml")) {    throw new Error("URL did not return HTML content");  }  const buffer = await res.arrayBuffer();  if (buffer.byteLength > MAX_HTML_BYTES) {    throw new Error("HTML response exceeds size limit");  }  return new TextDecoder().decode(buffer);}

DeploymentCopy Anchor Link

curl "https://your-worker.workers.dev/stats?url=https://example.com"

Local DevelopmentCopy Anchor Link

cd apps/experiments/html-rewriter
npm install
npm run dev

Test locally:

curl "http://localhost:8787/stats?url=https://example.com"
curl "http://localhost:8787/transform?url=https://example.com"

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• HTMLRewriter - Streaming HTML parsing and transformation
• Fetch API - Remote HTML retrieval