Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JSDOM
✓ import { JSDOM } from 'jsdom';
✗ const { JSDOM } = require('jsdom');
While CommonJS `require` is still supported, ESM imports are the standard for modern Node.js development. For CommonJS, use `const { JSDOM } = require('jsdom');`
VirtualConsole
✓ import { VirtualConsole } from 'jsdom';
✗ const VirtualConsole = require('jsdom').VirtualConsole;
Used for custom handling of console messages within the JSDOM window environment. For CommonJS, use `const { VirtualConsole } = require('jsdom');`
ResourceLoader
✓ import { ResourceLoader } from 'jsdom';
✗ const ResourceLoader = require('jsdom').ResourceLoader;
For custom resource loading behavior (e.g., intercepting HTTP requests). The API for this class was significantly overhauled in v28.0.0. For CommonJS, use `const { ResourceLoader } = require('jsdom');`
Demonstrates creating a JSDOM instance, accessing its window and document, manipulating elements, simulating user interaction, and proper cleanup.
import { JSDOM } from 'jsdom';
// Basic usage: create a DOM from an HTML string
const dom = new JSDOM(`<!DOCTYPE html>
<html>
<head><title>My Page</title></head>
<body>
<p id="greeting">Hello, JSDOM!</p>
<button onclick="document.querySelector('#greeting').textContent = 'Button Clicked!';">Click Me</button>
</body>
</html>`, {
url: "https://example.org/",
referrer: "https://example.com/",
contentType: "text/html",
includeNodeLocations: true // Useful for debugging script errors
});
const { window } = dom;
const { document } = window;
// Access and manipulate the DOM
console.log(document.title); // My Page
const greetingParagraph = document.getElementById("greeting");
console.log(greetingParagraph?.textContent); // Hello, JSDOM!
// Simulate a click event, executing inline script
const button = document.querySelector('button');
button?.click();
console.log(greetingParagraph?.textContent); // Button Clicked!
// Clean up the window object to prevent memory leaks
dom.window.close();
Debug
Known issues
breakingjsdom v29.0.0 and later require Node.js v22.13.0+, v20.19.0+, or v24.0.0+.fixUpgrade your Node.js environment to a supported version (e.g., `nvm install 22` or `nvm use 22`).
affects: >=29.0.0
breakingThe CSSOM implementation was completely overhauled in v29.0.0, replacing `@acemir/cssom` and `cssstyle` with internal implementations. This may change parsing behavior for complex CSS or break direct interactions with previous internal CSS objects.fixReview CSS parsing and `getComputedStyle()` usage. If custom CSS processing was tied to the old dependencies, update it to reflect the new internal implementation or use `css-tree` directly if advanced AST manipulation is needed.
affects: >=29.0.0
breakingThe resource loading customization API was overhauled in v28.0.0. Existing custom `ResourceLoader` implementations will likely break.fixConsult the jsdom README or documentation for v28.0.0+ regarding the new `ResourceLoader` API and update your custom resource loading logic accordingly.
affects: >=28.0.0
gotchaA regression in v28.0.0 means `WebSocket`s are no longer correctly throttled to one connection per origin due to an upstream Node.js `undici` bug.fixBe aware of potential increased WebSocket connection usage. Monitor upstream `undici` bug reports for a fix or upgrade to a jsdom version that incorporates a resolution if available.
affects: >=28.0.0 <29.0.0
gotchaEnabling `includeNodeLocations: true` in the JSDOM constructor options preserves HTML parser location info, which is useful for debugging but incurs a performance overhead. It is also incompatible with XML content types.fixOnly enable `includeNodeLocations: true` when necessary for debugging or source mapping. Keep it `false` (default) for performance-critical scenarios. Do not use with `contentType: 'application/xml'`.
affects: >=1.0.0
gotchaThe `storageQuota` option limits `localStorage` and `sessionStorage` size. Exceeding the default 5MB (5,000,000 code units) per origin will throw a `DOMException` of type `QuotaExceededError`.fixHandle `QuotaExceededError` exceptions when interacting with `localStorage` or `sessionStorage`. Increase `storageQuota` in the `JSDOM` constructor options if more storage is legitimately required, e.g., `{ storageQuota: 20000000 }`. affects: >=1.0.0
Errors
Common errors & fixes
Error: Your current Node.js version (vXX.Y.Z) is not supported by jsdom. Please upgrade to Node.js v22.13.0 or higher.
Attempting to run jsdom v29.0.0 or newer with an unsupported Node.js version.
fixUpgrade your Node.js runtime to `^20.19.0`, `^22.13.0`, or `^24.0.0` or a newer compatible version as specified in the package's `engines` field.
DOMException: QuotaExceededError: The quota has been exceeded.
An application running within the JSDOM environment attempted to store more data in `localStorage` or `sessionStorage` than the `storageQuota` allows.
fixIncrease the `storageQuota` in the JSDOM constructor options, for example: `new JSDOM(html, { storageQuota: 10 * 1024 * 1024 })` for 10MB, or reduce the amount of data being stored. TypeError: The "init" argument must be an object of type ResourceLoaderInit
Using a custom `ResourceLoader` class or configuration with `jsdom` v28.0.0 or newer that adheres to an older API specification.
fixReview the jsdom documentation for v28.0.0+ regarding `ResourceLoader` customization. The API was overhauled; your `ResourceLoader` implementation needs to be updated to match the new `ResourceLoaderInit` interface.
Audit
Dependencies
canvasoptionalOptional peer dependency for rendering canvas elements in the JSDOM environment.