Skip to content

Latest commit

 

History

History
112 lines (80 loc) · 5.54 KB

README.md

File metadata and controls

112 lines (80 loc) · 5.54 KB
Raw

HTML Rewriter

WASM-based implementation of Cloudflare's HTML Rewriter for use in Deno, browsers, etc.

It uses lol-html under the hood, the same implementation used by Cloudflare Workers. It is based on Miniflare's WASM build.

Installation

This package includes 2 versions of HTML Rewriter.

index.ts loads the WASM that is co-located with this module via fetch and (streaming-) instantiates the module that way. In Deno, this works via file system (if you've downloaded the module) and web (when loading from deno.land/x or even githubusercontent.com). However, if you are using this version with other tooling, depending on the bundler and configuration the WASM source may or may not be included...

base64.ts has the required WASM inlined as compressed base64. The total size is 447K (345K gzipped). This ensures that HTML Rewriter is working properly when bundled, offline, etc. The "hackyness" of ~400K of inlined WASM and relying on DecompressionStream is significant (without compression, the file size would be 1.2MB), but its simplicity makes it easier to get it to work with various bundlers (including Deno's own, as of this writing).

Use in Browser

For use in the browser it's best to install the "node-ified" package from npm and use it with a bundler.

npm install @worker-tools/html-rewriter

Which version of HTML Rewriter to pick depends on which bundler you are using:

For Webpack 4, it's best to use the non-ESM base64 version via its full path: @worker-tools/html-rewriter/script/base64.

Webpack 5 treats the regular version correctly by default, which can be imported as @worker-tools/html-rewriter.

For esbuild it's best to use the base64-version via @worker-tools/html-rewriter/base64.

You can explore the full contents of the npm package here.

Usage

import { 
  HTMLRewriter 
} from 'https://ghuc.cc/worker-tools/html-rewriter/index.ts'

new HTMLRewriter()
  .on("p", {
    element(element) { 
      element.tagName = "h1" 
    },
  })
  .transform(new Response('<p class="red">test</p>'))
  .text().then(x => console.log(x))

For more on how to use HTMLRewriter, see the Cloudflare Workers Docs.

Building

Make sure you've initialized all git submodules. It is 2 levels deep.

git submodule update --init --recursive

Make sure you have rustup installed. Then run

make dist

This will build a custom version of wasm-pack first, then use it to compile lol-html to WASM. Please see the submodules for details on why this is necessary.

This module is part of the Worker Tools collection
⁕

Worker Tools are a collection of TypeScript libraries for writing web servers in Worker Runtimes such as Cloudflare Workers, Deno Deploy and Service Workers in the browser.

If you liked this module, you might also like:

  • 🧭 Worker Router --- Complete routing solution that works across CF Workers, Deno and Service Workers
  • 🔋 Worker Middleware --- A suite of standalone HTTP server-side middleware with TypeScript support
  • 📄 Worker HTML --- HTML templating and streaming response library
  • 📦 Storage Area --- Key-value store abstraction across Cloudflare KV, Deno and browsers.
  • 🆗 Response Creators --- Factory functions for responses with pre-filled status and status text
  • 🎏 Stream Response --- Use async generators to build streaming responses for SSE, etc...
  • 🥏 JSON Fetch --- Drop-in replacements for Fetch API classes with first class support for JSON.
  • 🦑 JSON Stream --- Streaming JSON parser/stingifier with first class support for web streams.

Worker Tools also includes a number of polyfills that help bridge the gap between Worker Runtimes:

Fore more visit workers.tools.