JSDOM: JavaScript DOM Implementation for Node.js

Common errors

• Error: Your current Node.js version (vXX.Y.Z) is not supported by jsdom. Please upgrade to Node.js v22.13.0 or higher.

  cause Attempting to run jsdom v29.0.0 or newer with an unsupported Node.js version.
  fix Upgrade 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.

  cause An application running within the JSDOM environment attempted to store more data in `localStorage` or `sessionStorage` than the `storageQuota` allows.
  fix Increase 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

  cause Using a custom `ResourceLoader` class or configuration with `jsdom` v28.0.0 or newer that adheres to an older API specification.
  fix Review 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.

Warnings

• breaking jsdom v29.0.0 and later require Node.js v22.13.0+, v20.19.0+, or v24.0.0+.
  Fix: Upgrade your Node.js environment to a supported version (e.g., `nvm install 22` or `nvm use 22`).
• breaking The 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.
  Fix: Review 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.
• breaking The resource loading customization API was overhauled in v28.0.0. Existing custom `ResourceLoader` implementations will likely break.
  Fix: Consult the jsdom README or documentation for v28.0.0+ regarding the new `ResourceLoader` API and update your custom resource loading logic accordingly.
• gotcha A 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.
  Fix: Be 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.
• gotcha Enabling `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.
  Fix: Only 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'`.
• gotcha The `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`.
  Fix: Handle `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 }`.

Install

• npm install jsdom npm
• yarn add jsdom yarn
• pnpm add jsdom pnpm

Imports

• JSDOM
  wrong:

  const { JSDOM } = require('jsdom');

  correct:

  import { JSDOM } from '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
  wrong:

  const VirtualConsole = require('jsdom').VirtualConsole;

  correct:

  import { VirtualConsole } from 'jsdom';

  Used for custom handling of console messages within the JSDOM window environment. For CommonJS, use `const { VirtualConsole } = require('jsdom');`
• ResourceLoader
  wrong:

  const ResourceLoader = require('jsdom').ResourceLoader;

  correct:

  import { ResourceLoader } from 'jsdom';

  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');`

Quickstart

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();