Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/deno_dom/README.md

Browser DOM & HTML parser in Deno
b-fuze/deno-dom
Very Popular
Go to Latest
File

Deno DOM

An implementation of the browser DOM—primarily for SSR—in Deno. Implemented with Rust, WASM, and obviously, Deno/TypeScript.

Example

import { DOMParser, Element } from "https://deno.land/x/deno_dom/deno-dom-wasm.ts";

const doc = new DOMParser().parseFromString(`
  <h1>Hello World!</h1>
  <p>Hello from <a href="https://deno.land/">Deno!</a></p>
`, "text/html")!;

const p = doc.querySelector("p")!;

console.log(p.textContent); // "Hello from Deno!"
console.log(p.childNodes[1].textContent); // "Deno!"

p.innerHTML = "DOM in <b>Deno</b> is pretty cool";
console.log(p.children[0].outerHTML); // "<b>Deno</b>"

Deno DOM has two backends, WASM and native using Deno native plugins. Both APIs are identical, the difference being only in performance. The WASM backend works with all Deno restrictions, but the native backend requires the --unstable --allow-plugin flags. You can switch between them by importing either deno-dom-wasm.ts or deno-dom-native.ts.

Deno DOM is still under development, but is fairly usable for basic HTML manipulation needs.

Documentation

Refer to MDN (Mozilla Developer Network) for documentation. If there are inconsistencies (that aren’t a result of legacy APIs) file an issue.

Goals

  • HTML parser in Deno
  • Fast
  • Mirror most supported DOM APIs as closely as possible
  • Provide specific APIs in addition to DOM APIs to make certain operations more efficient, like controlling Shadow DOM (see Open Questions)
  • Use cutting-edge JS features like private class members, optional chaining, etc

Non-Goals

  • Headless browser implementation
  • Ability to run JS embedded in documents (<script> tags, onload, etc)
  • Parse CSS or JS (they’re just text, but this may be supported in the future for CSSOM)
  • Support older (or even not so old) JS engines. In other words, there will be no support of transpilation to ES5, no support of polyfills, etc
  • Support special functionality of obsolete HTML elements (<marquee>, etc)

Running tests

To run tests (test/units and WPT tests) use the following for WASM

deno test --allow-read wasm.test.ts

Or the following for native (native requires more permissions)

deno test --unstable --A native.test.ts

WPT tests are still a WIP, passed tests likely haven’t actually passed.

Building Deno DOM Native

Deno DOM native is a faster backend for Deno DOM (check benchmarks), however, the WASM backend is sufficient for almost all use-cases.

Note: If you’re running an x86_64 system with either Windows, Linux, or macOS, then you probably don’t need to build the plugin. Deno DOM native downloads a prebuilt binary in those cases.

To build Deno DOM’s native backend, install Rust if you haven’t already, then run

cargo build --release

which produces a binary located at target/release/libplugin.{so,dll,dylib} (extension depends on your system).

To use the new binary you need to set the DENO_DOM_PLUGIN env var to the path of the binary produced in the previous step. Don’t forget to run Deno with --allow-env.

Credits

  • html5ever developers for the HTML parser
  • nwsapi developers for the selector parser