jsdom

jsdom is a pure-JavaScript implementation of many web standards, most notably the WHATWG DOM and HTML specifications, built to run inside Node.js. It emulates enough of a browser environment to parse HTML into a live document, expose the familiar window and document globals, run scripts, handle events, and fetch subresources, without needing an actual browser or headless Chromium.

It is the DOM engine behind much of the JavaScript testing ecosystem and a workhorse for server-side HTML processing and scraping. You give the JSDOM constructor a string of markup and get back a fully navigable document you can query with standard DOM APIs, manipulate, and serialize back to HTML.

What You Get

• A JSDOM constructor that parses HTML or XML into a live, spec-compliant window/document pair
• Standard DOM APIs, including querySelector, events, mutation observers, ranges, and node traversal
• Configurable script execution, subresource loading, cookies, virtual console, and custom resource loaders
• Convenience factories such as JSDOM.fromFile() and JSDOM.fromURL() plus serialization back to HTML

Common Use Cases

• Providing the DOM environment for unit tests run under Jest, Vitest, or Mocha
• Server-side scraping and extraction of data from real-world HTML pages
• Rendering, inspecting, or transforming HTML documents in Node.js pipelines

Under The Hood

Architecture - The public surface lives in lib/api.js, whose JSDOM class normalizes the input HTML, transforms user options, builds a window via createWindow (lib/jsdom/browser/Window.js), and parses markup into a document with parseIntoDocument before closing it. The bulk of the implementation is the lib/jsdom/living/ tree, roughly 35 modules mapping to web-standard areas such as nodes, events, xhr, fetch, css, webstorage, range, custom-elements, and mutation-observer, with IDL interfaces generated from Web IDL. Convenience factories (fromFile, fromURL), a VirtualConsole, a loose CookieJar, and a pluggable resource/dispatcher layer round out the design.

Tech Stack - jsdom is written in JavaScript using CommonJS modules and targets modern Node.js (engines ^20.19 || ^22.13 || >=24). It composes a suite of standards-focused dependencies: parse5 for HTML parsing, saxes and xml-name-validator for XML, whatwg-url and whatwg-mimetype for URL/MIME handling, undici for fetch, tough-cookie for cookies, css-tree/@asamuzakjp packages for CSS, and webidl-conversions/decimal.js for type coercion. Interface bindings are generated with webidl2js, and the build is orchestrated with wireit.

Code Quality - The project is mature and rigorously tested. Beyond its own test/api suite run with Mocha, it validates conformance against the shared Web Platform Tests (test/web-platform-tests), a strong signal of standards fidelity. It ships an ESLint flat config, contributor and maintainer guides, and benchmarks. The codebase is large but consistently organized by specification area, and error handling follows DOM semantics (e.g. throwing DOMException on quota or parse violations).

API Design - The developer experience is deliberately browser-like: import jsdom, destructure JSDOM, and pass a markup string to get a working window/document. A single options object exposes advanced behavior (url, runScripts, resources, includeNodeLocations, storageQuota) with safe, performance-minded defaults, and static async factories cover file and URL sources. Named exports (JSDOM, VirtualConsole, CookieJar, ResourceLoader) and thorough README documentation keep the boilerplate minimal for common cases while leaving escape hatches for advanced use.