Edge HTML Rewriting: The Complete 2026 Guide

HTML rewriting at the edge lets you modify a page's HTML after it leaves the origin server but before it reaches the browser or crawler. This technique solves a persistent problem in technical SEO: what do you do when you cannot modify the application code but need to change meta tags, inject...

How HTML Rewriting Works

Traditional approaches to HTML modification require server-side includes, template changes, or middleware proxies. Edge rewriting operates on the streaming HTML response. Instead of loading the entire document into memory, modern edge runtimes use streaming parsers that process the HTML as it passes through.

Cloudflare's HTMLRewriter is the most widely deployed example. It uses a jQuery-like selector API to register handlers for specific elements. When the stream passes through the worker, matching elements trigger your callback, and you can modify attributes, text content, or remove and append elements.

async function handleRequest(request) {
  const response = await fetch(request)
  return new HTMLRewriter()
    .on('title', {
      element(el) {
        el.setInnerContent('Optimized Title | Site Name')
      }
    })
    .on('meta[name="description"]', {
      element(el) {
        el.setAttribute('content', 'New meta description for SEO')
      }
    })
    .transform(response)
}

The key advantage is that HTMLRewriter never buffers the full response. It processes chunks as they arrive, keeping memory usage low even for large pages.

Common SEO Transformations

Canonical Tag Injection

Many CMS platforms and legacy sites hardcode or omit canonical tags. An edge worker can inject or override them based on URL patterns.

.on('link[rel="canonical"]', {
  element(el) {
    const url = new URL(request.url)
    el.setAttribute('href', url.origin + url.pathname)
  }
})

For sites missing canonical tags entirely, you can append a new element to the head section.

Structured Data Injection

JSON-LD schema markup can be injected into the page head, enabling rich results without modifying CMS templates.

.on('head', {
  element(el) {
    const schema = {
      '@context': 'https://schema.org',
      '@type': 'Article',
      'headline': pageTitle,
      'datePublished': publishDate,
    }
    el.append(`<script type="application/ld+json">${JSON.stringify(schema)}</script>`, { html: true })
  }
})

Hreflang Tag Management

International sites often struggle with hreflang implementation. Edge workers can inspect the request URL and inject the correct hreflang link tags based on a language mapping configuration.

.on('head', {
  element(el) {
    const langMap = getLanguageMap(url.pathname)
    for (const [lang, href] of Object.entries(langMap)) {
      el.append(`<link rel="alternate" hreflang="${lang}" href="${href}" />`, { html: true })
    }
  }
})

Performance Considerations

Streaming HTML rewriting adds minimal overhead. Cloudflare's HTMLRewriter typically adds 1-5 milliseconds per request. The transformation happens on the CDN edge, so the round trip from origin is already completed by the time rewriting begins.

Be selective with selectors. Each registered handler adds processing per matching element. For high-traffic pages, minimize the number of selectors and keep handler logic lightweight. Avoid synchronous API calls inside handlers because they block the stream.

When Not to Rewrite

HTML rewriting cannot fix problems that require server-side data access. If your page lacks structured data because the CMS stores it in a database not accessible at the edge, you cannot inject it from a worker alone. Similarly, rewriting is constrained by the worker's memory and CPU limits. Pages exceeding 5 MB or containing deeply nested DOM trees may exceed platform limits.

Audit

Edge HTML rewriting is one of the most powerful techniques in the edge SEO toolkit. It allows SEO teams to patch pages, fix markup, and inject structured data without touching the application codebase. Streaming parsers keep performance overhead negligible. For any site where CMS changes are slow, expensive, or blocked by organizational constraints, edge HTML rewriting provides an immediate, reversible alternative.

Citations

Cloudflare. "HTMLRewriter API Reference." developers.cloudflare.com/workers/runtime-apis/html-rewriter 2. Google. "Rich Results Test Developer Guide." developers.google.com/search/docs/appearance/structured-data/rich-results-test 3. Google Search Central. "Hreflang Tag Guide." developers.google.com/search/docs/specialty/international/localized-versions 4. Cloudflare. "Streaming HTML Rewriting Performance Benchmarks." blog.cloudflare.com/html-rewriter-performance

Ready to Build Your Dream Website?

Let's discuss your project and create something amazing together.