Skip to main content

​
Overview

HTMLRewriter lets you modify HTML responses as they stream through your edge script. It parses HTML on the fly and calls your handler functions when it encounters matching elements, comments, or text without buffering the entire document in memory.

​
Quick Start

A simple middleware example: 
import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .on("h1", {
        element(el) {
          el.setInnerContent("Modified Title");
        },
      })
      .transform(response);
  });

​
Constructor

new HTMLRewriter(options?)
​
options
object

​
Methods

​
on(selector, handlers)

Registers handlers for elements matching a CSS selector. Returns this for chaining. 
rewriter.on("div.content", {
  element(el) { /* ... */ },
  comments(comment) { /* ... */ },
  text(text) { /* ... */ },
});
​
selector
string
required
A CSS selector. See supported selectors below.
​
handlers
ElementHandlers
required
An object with optional handler functions. Each handler can be sync or async.

​
onDocument(handlers)

Registers document-level handlers. Returns this for chaining. 
rewriter.onDocument({
  doctype(doctype) { /* ... */ },
  comments(comment) { /* ... */ },
  text(text) { /* ... */ },
  end(end) { /* ... */ },
});
​
handlers
DocumentHandlers
required

​
transform(response)

Applies all registered handlers to the response body and returns a new Response. 
const transformed = rewriter.transform(response);
​
response
Response
required
The HTTP response to transform. Must not be an error response.
Returns: A new Response with:
  • The same headers (minus Content-Length, since the body length may change)
  • A streaming body with the transformed HTML

​
Handler Types

​
Element

Passed to element handlers. Represents an HTML opening tag.

​
Properties

PropertyTypeDescription
tagNamestringTag name (lowercase). Readable and writable.
namespaceURIstringNamespace URI (readonly).
removedbooleanWhether the element has been removed (readonly).
attributesIterableIterator<[string, string]>Iterable of [name, value] pairs (readonly).

​
Attribute Methods

getAttribute(name)
Returns the value of the attribute with the given name, or null if the attribute does not exist.
​
name
string
required
The attribute name.
Returns: string | null
hasAttribute(name)
Returns whether the element has an attribute with the given name.
​
name
string
required
The attribute name.
Returns: boolean
setAttribute(name, value)
Sets the value of the attribute with the given name. Adds the attribute if it does not exist.
​
name
string
required
The attribute name.
​
value
string
required
The attribute value.
Returns: Element — the element itself, for chaining.
removeAttribute(name)
Removes the attribute with the given name. No-op if the attribute does not exist.
​
name
string
required
The attribute name.
Returns: Element — the element itself, for chaining. Setters return the element itself, so calls can be chained: 
el.setAttribute("class", "new")
  .setAttribute("id", "main")
  .removeAttribute("style");

​
Content Mutation Methods

All content mutation methods accept content as a string, ReadableStream<Uint8Array>, or Response, and an optional options object. They all return Element for chaining.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to insert. Strings are inserted directly. Streams and Response bodies are consumed and piped into the output.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
before(content, options?)
Inserts content immediately before the element’s opening tag. Returns: Element
after(content, options?)
Inserts content immediately after the element’s closing tag. Returns: Element
prepend(content, options?)
Inserts content at the beginning of the element, right after the opening tag. Returns: Element
append(content, options?)
Inserts content at the end of the element, right before the closing tag. Returns: Element
replace(content, options?)
Replaces the entire element (opening tag, content, and closing tag) with the provided content. Returns: Element
setInnerContent(content, options?)
Replaces the element’s inner content, keeping the opening and closing tags. Returns: Element 
el.before("<hr>", { html: true })
  .setInnerContent("Hello")
  .after("<hr>", { html: true });

​
Removal Methods

remove()
Removes the element and all of its content (opening tag, children, closing tag). Returns: Element
removeAndKeepContent()
Removes the element’s opening and closing tags but keeps the inner content in place. Returns: Element

​
End Tag Handler

onEndTag(handler)
Registers a handler that is called when the element’s closing tag is encountered.
​
handler
(endTag: EndTag) => void | Promise<void>
required
A callback receiving the EndTag object. Can be async.
Returns: void 
el.onEndTag((endTag) => {
  endTag.before("<hr>", { html: true });
});

​
Comment

Passed to comments handlers.

​
Properties

PropertyTypeDescription
textstringThe comment text, without <!-- and -->. Readable and writable.
removedbooleanWhether the comment has been removed (readonly).

​
Methods

before(content, options?)
Inserts content immediately before the comment.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to insert.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: Comment
after(content, options?)
Inserts content immediately after the comment.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to insert.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: Comment
replace(content, options?)
Replaces the comment with the provided content.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to replace with.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: Comment
remove()
Removes the comment from the document. Returns: Comment

​
TextChunk

Passed to text handlers. Note: a single text node may be split across multiple chunks.

​
Properties

PropertyTypeDescription
textstringThe text content (readonly).
lastInTextNodebooleantrue if this is the last chunk in the text node (readonly).
removedbooleanWhether this chunk has been removed (readonly).

​
Methods

before(content, options?)
Inserts content immediately before the text chunk.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to insert.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: TextChunk
after(content, options?)
Inserts content immediately after the text chunk.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to insert.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: TextChunk
replace(content, options?)
Replaces the text chunk with the provided content.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to replace with.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: TextChunk
remove()
Removes the text chunk from the document. Returns: TextChunk

​
EndTag

Passed to onEndTag handlers.

​
Properties

PropertyTypeDescription
namestringThe end tag name. Readable and writable.

​
Methods

before(content, options?)
Inserts content immediately before the end tag.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to insert.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: EndTag
after(content, options?)
Inserts content immediately after the end tag.
​
content
string | ReadableStream<Uint8Array> | Response
required
The content to insert.
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: EndTag
remove()
Removes the end tag from the document. Returns: EndTag

​
Doctype

Passed to doctype handlers. All properties are read-only.

​
Properties

PropertyTypeDescription
namestring | nullThe doctype name (e.g. "html").
publicIdstring | nullThe PUBLIC identifier.
systemIdstring | nullThe SYSTEM identifier.

​
DocumentEnd

Passed to end handlers.

​
Methods

append(content, options?)
Appends content at the end of the document.
​
content
string
required
The content to append. Only accepts string (not streams or responses).
​
options.html
boolean
default:false
When true, content is inserted as raw HTML. When false, content is escaped as text.
Returns: DocumentEnd 
end.append("<!-- generated -->", { html: true });

​
Supported CSS Selectors

The following CSS selectors are supported, based on the W3C Selectors Level 4 specification.
SelectorDescriptionSpec
*Any elementUniversal selector
EElement of type EType selector
E.classElement with classClass selector
E#idElement with IDID selector
E:nth-child(n)The n-th child of its parent:nth-child()
E:first-childFirst child of its parent:first-child
E:nth-of-type(n)The n-th sibling of its type:nth-of-type()
E:first-of-typeFirst sibling of its type:first-of-type
E:not(s)Element that does not match compound selector s:not()
E[attr]Element with attribute attrAttribute selector
E[attr="value"]Attribute exactly equals valueAttribute selector
E[attr="value" i]Case-insensitive attribute matchCase sensitivity
E[attr="value" s]Case-sensitive attribute matchCase sensitivity
E[attr~="value"]Whitespace-separated list containing valueAttribute selector
E[attr^="value"]Attribute starts with valueAttribute selector
E[attr$="value"]Attribute ends with valueAttribute selector
E[attr*="value"]Attribute contains valueAttribute selector
E[attr|="value"]Hyphen-separated attribute starting with valueAttribute selector
E FF descendant of EDescendant combinator
E > FF direct child of EChild combinator

​
Examples

import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .on("a[href]", {
        element(el) {
          const href = el.getAttribute("href");
          if (href?.startsWith("http://")) {
            el.setAttribute("href", href.replace("http://", "https://"));
          }
        },
      })
      .transform(response);
  });

​
Inject a Script

import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .onDocument({
        end(end) {
          end.append('<script src="/analytics.js"></script>', { html: true });
        },
      })
      .transform(response);
  });

​
Remove Elements

import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .on("script[src*='tracker']", {
        element(el) {
          el.remove();
        },
      })
      .on(".cookie-banner", {
        element(el) {
          el.remove();
        },
      })
      .transform(response);
  });

​
Async Handler

Handlers can return a Promise for async operations like sub-requests. 
import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .on("include[src]", {
        async element(el) {
          const src = el.getAttribute("src");
          const partial = await fetch(src);
          el.replace(partial.body, { html: true });
        },
      })
      .transform(response);
  });

​
Class-Based Handlers

Instead of inline objects, you can define handler classes and pass instances to .on() or .onDocument(). 
import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

class AttributeRewriter {
  #attrName;

  constructor(attrName) {
    this.#attrName = attrName;
  }

  element(el) {
    const value = el.getAttribute(this.#attrName);
    if (value) {
      el.setAttribute(this.#attrName, value.replace("http://", "https://"));
    }
  }
}

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .on("a", new AttributeRewriter("href"))
      .on("img", new AttributeRewriter("src"))
      .transform(response);
  });

​
Document Handler Class

import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

class StripComments {
  comments(comment) {
    comment.remove();
  }

  end(end) {
    end.append("<!-- cleaned -->", { html: true });
  }
}

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .onDocument(new StripComments())
      .transform(response);
  });

​
Async Class Handler

Class methods can be async just like inline handlers. 
import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

class IncludeExpander {
  async element(el) {
    const src = el.getAttribute("src");
    if (src) {
      const partial = await fetch(src);
      el.replace(partial.body, { html: true });
    }
  }
}

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .on("include[src]", new IncludeExpander())
      .transform(response);
  });

​
Multiple Selectors

Chain multiple .on() calls to handle different elements independently. 
import * as BunnySDK from "https://esm.sh/@bunny.net/edgescript-sdk@0.11.2";

BunnySDK.net.http.servePullZone()
  .onOriginResponse(async ({ response }) => {
    return new HTMLRewriter()
      .on("title", {
        element(el) {
          el.setInnerContent("My Site");
        },
      })
      .on("meta[name='description']", {
        element(el) {
          el.setAttribute("content", "Custom description");
        },
      })
      .on("img", {
        element(el) {
          el.setAttribute("loading", "lazy");
        },
      })
      .transform(response);
  });

​
References