Cloudflare Workers: Async Transformations for HTMLRewriter

HTMLRewriter, Cloudflare's streaming HTML transformation tool for Workers, has been a practical way to modify documents at the edge since its launch last year. But until now, handlers were limited to synchronous operations. Cloudflare has announced support for async handlers, meaning handlers can now await other tasks—such as fetching user-specific content or checking the status of external resources—while processing a document.

The parser underneath HTMLRewriter was built in Rust and processes HTML as a stream, rather than loading the whole document into memory like a conventional DOM parser. This keeps time-to-first-byte low and makes edge-side modification efficient. Because transformation happens chunk by chunk, a user generally has no way to tell the HTML was ever rewritten.

Running Async Logic in Handlers

Previously, a handler was a simple function that ran synchronously. The new capability lets you define a handler as async, which means it can use await and work with Promises. That opens up possibilities that were awkward or impossible to handle in a streaming pipeline, like personalizing HTML based on feature flags, user identity, or CMS data that isn’t known until request time.

Assigning handlers to elements still follows the same jQuery-style pattern: define the logic, associate it with a CSS selector, and let the system apply it. Selector support has also grown; it now includes nth-child, so you can target elements based on their position in the document (for example, changing the alt text of every second image on a page).

Practical Example: Restoring Missing Images

A practical demonstration from Cloudflare shows how async handlers can be used to repair stale or broken assets on older web pages. Static sites often accumulate dead links and missing images over time. One Cloudflare engineer wrote a Worker script that checks each img element against the Internet Archive API. If an image is no longer available, the handler rewrites the URL to the latest archived version—so visitors never see a broken placeholder.

The improvement means the transformation can bridge across external services at runtime. A handler in this pattern could also ping a monitoring service like Sentry about a broken asset, without constructing extra response logic separately.

A working version of the image-restoration example is available in the Workers Playground, and Cloudflare's developer documentation includes details on deployment and selector options for anyone wanting to implement it on their own site.

Community Projects Using HTMLRewriter

Since the API first became available, developers have used it for a range of creative tasks. Several projects have been highlighted by Cloudflare, including:

  • Building a lightweight web scraper directly in a Worker
  • Adding native image lazy loading to Ghost blogs
  • Localizing on-the-fly site content based on the requester's locale
  • Extending blog platforms by injecting custom HTML per page
  • Prefetching and embedding web fonts at the edge

The updated HTMLRewriter documentation is the place to start for developers who want to explore asynchronous handlers. Cloudflare says it is keen to see more use cases, sharing projects under @CloudflareDev.