html-rewriter-wasm

When using async handlers, the implementation uses WebAssembly Asyncify to unwind the stack. This imposes strict concurrency constraints:

1. No concurrent writes/ends: You must await every call to .write() and .end() before calling them again. You cannot use Promise.all() on multiple .write() calls.
2. Register handlers early: You cannot add new handlers via .on() after .write() or .end() has been called.
3. Single use of .end(): The .end() method can only be called once per instance. Create a new HTMLRewriter instance for every new transformation task.

// ✅ Correct pattern for async handlers
const rewriter = new HTMLRewriter(...).on("p", {
  async element(element) {
    await fetch(...);
    element.setInnerContent("new");
  }
});

await rewriter.write(encoder.encode("<p>1</p>"));
await rewriter.write(encoder.encode("<p>2</p>"));
await rewriter.end();

The HTMLRewriter class allows you to transform HTML content using handlers. You instantiate it with a callback function that receives chunks of the transformed output. You then register handlers using .on(selector, handler) and process data using .write(encodedChunk) and .end().

Important: You must call .free() on the instance to release WebAssembly memory once you are finished with the rewriter.

import { HTMLRewriter } from "html-rewriter-wasm";

const encoder = new TextEncoder();
const decoder = new TextDecoder();

let output = "";
const rewriter = new HTMLRewriter((outputChunk) => {
  output += decoder.decode(outputChunk);
});

rewriter.on("p", {
  element(element) {
    element.setInnerContent("new");
  },
});

try {
  await rewriter.write(encoder.encode("<p>old</p>"));
  await rewriter.end();
  console.log(output); // <p>new</p>
} finally {
  rewriter.free(); // Remember to free memory
}

The Element class provides methods to modify HTML elements matched by a selector.

Attribute Manipulation:

• getAttribute(name: string): string | null
• hasAttribute(name: string): boolean
• setAttribute(name: string, value: string): this
• removeAttribute(name: string): this
• attributes: An IterableIterator<[string, string]> of all attributes.

Content and Structure Manipulation:

• before(content: string, options?: ContentTypeOptions): Inserts content before the element.
• after(content: string, options?: ContentTypeOptions): Inserts content after the element.
• prepend(content: string, options?: ContentTypeOptions): Inserts content at the start of the element.
• append(content: string, options?: ContentTypeOptions): Inserts content at the end of the element.
• replace(content: string, options?: ContentTypeOptions): Replaces the element with new content.
• setInnerContent(content: string, options?: ContentTypeOptions): Replaces the element's inner content.
• remove(): Removes the element.
• removeAndKeepContent(): Removes the element but keeps its children.

Lifecycle and Metadata:

• tagName: string
• namespaceURI: string
• removed: boolean
• onEndTag(handler: (endTag: EndTag) => void | Promise<void>): void: Registers a callback for when the element's closing tag is encountered.

The HTMLRewriter class is the primary entry point for parsing and transforming HTML streams. You initialize it with an outputSink function that receives chunks of the transformed HTML as Uint8Array.

To perform transformations, use .on(selector, handlers) to target specific elements, or .onDocument(handlers) to target document-level events like doctypes or the end of the document. After setting up handlers, feed HTML chunks into the rewriter using .write(chunk) and finalize the process with .end().

const output: Uint8Array[] = [];
const rewriter = new HTMLRewriter((chunk) => {
  output.push(chunk);
});

rewriter
  .on('a', {
    element(element) {
      element.setAttribute('class', 'transformed-link');
    }
  })
  .onDocument({
    end(docEnd) {
      docEnd.append('<!-- End of Document -->');
    }
  });

const encoder = new TextEncoder();
await rewriter.write(encoder.encode('<html><body><a href="#">Link</a></body></html>'));
await rewriter.end();

const result = new TextDecoder().decode(new Uint8Array(await Promise.all(output.map(async (c) => c))));
// result: <html><body><a class="transformed-link" href="#">Link</a></body></html>