jsdom — JavaScript DOM Implementation for Node.js

Introduction

jsdom is a pure-JavaScript implementation of many web standards, notably the WHATWG DOM and HTML Standards. It allows you to create and manipulate a browser-like DOM environment entirely in Node.js, which is essential for server-side rendering, testing, and scraping.

What jsdom Does

• Parses HTML and produces a full DOM tree accessible via standard APIs
• Implements core web standards including DOM, HTML, URL, and Fetch
• Executes inline and external JavaScript within the simulated document
• Supports custom user agents, referrers, cookies, and content types
• Provides WHATWG URL and Encoding APIs for standards-compliant parsing

Architecture Overview

jsdom uses parse5 as its HTML parser to construct a DOM tree that conforms to the WHATWG DOM specification. The tree is wrapped in a Window object that exposes standard APIs like document, navigator, and console. Script execution runs through the Node.js VM module with configurable resource loading. Each JSDOM instance is isolated with its own window scope, making parallel test runs safe.

Self-Hosting & Configuration

• Install via npm or yarn into any Node.js project (no native deps required)
• Set url, referrer, and contentType options when creating a new JSDOM instance
• Configure runScripts: "dangerously" to execute scripts inside the DOM
• Use pretendToBeVisual: true to enable requestAnimationFrame and cancel timers
• Control external resource loading with the resources option and custom loaders

Key Features

• Full WHATWG DOM Level 4 implementation in pure JavaScript
• No headless browser binary needed, keeping CI environments lightweight
• Supports cookies, session history, and navigation within the virtual DOM
• Works with popular testing frameworks like Jest, Mocha, and Vitest out of the box
• Processes CSS selectors via querySelector and querySelectorAll for DOM traversal

Comparison with Similar Tools

• Cheerio — faster for static HTML scraping but does not execute JavaScript or emulate a live DOM
• happy-dom — lighter alternative focused on speed, but implements fewer web standards
• Puppeteer — controls a real Chromium browser for full rendering fidelity, at the cost of heavier resource usage
• linkedom — memory-efficient DOM implementation but lacks script execution support

FAQ

Q: Does jsdom support modern CSS features? A: jsdom does not implement a full CSS engine or layout. It parses stylesheets but does not compute styles or render visually.

Q: Can I use jsdom with Jest? A: Yes. Set testEnvironment: "jsdom" in your Jest config and Jest will use jsdom as the default DOM environment for all tests.

Q: How does jsdom handle fetch and XMLHttpRequest? A: jsdom provides built-in implementations of both when resource loading is enabled, routing requests through Node.js HTTP modules.

Q: Is jsdom suitable for web scraping? A: It works well for scraping pages that require JavaScript execution. For static HTML parsing, Cheerio is typically faster.

Sources

• https://github.com/jsdom/jsdom
• https://github.com/jsdom/jsdom/wiki