or run

npx @tessl/cli init

Version

Files

docs

tile.json

tessl/npm-jsdom

A JavaScript implementation of many web standards

Workspace: tessl
Visibility: Public
Created: 8 days ago
Last updated: 8 days ago
Describes: pkg:npm/jsdom@27.4.x

To install, run

npx @tessl/cli install tessl/npm-jsdom@27.4.0

Overview Eval results

jsdom

jsdom is a pure-JavaScript implementation of many web standards, notably the WHATWG DOM and HTML Standards, for use with Node.js. It emulates enough of a subset of a web browser to be useful for testing and scraping real-world web applications.

Quick Start

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

// Create a jsdom instance
const dom = new JSDOM(`<!DOCTYPE html><p>Hello world</p>`);

// Access the window object
console.log(dom.window.document.querySelector("p").textContent); // "Hello world"

// Use destructuring for convenience
const { document } = (new JSDOM(`<!DOCTYPE html><div id="main"></div>`)).window;
const mainDiv = document.getElementById("main");

Package Information

Package Name: jsdom
Package Type: npm
Language: JavaScript
Installation: npm install jsdom

Core Imports

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

For ES modules:

import { JSDOM } from "jsdom";

Additional exports:

const { JSDOM, VirtualConsole, CookieJar, ResourceLoader, toughCookie } = require("jsdom");

Architecture Overview

jsdom is built around several key components:

JSDOM Class: The main entry point for creating DOM instances from HTML strings, files, or URLs
Window Object: Provides a complete browser-like environment with 180+ web standard interfaces
Virtual Console: Captures console output and jsdom warnings/errors
Resource Loading: Configurable system for loading external scripts, stylesheets, and other resources
Script Execution: Sandboxed JavaScript execution with configurable security levels
Cookie Management: Full cookie jar implementation for HTTP cookie handling

Core API

JSDOM Class

class JSDOM {
  constructor(input?: string | Buffer | ArrayBuffer | TypedArray, options?: JSDOMOptions);
  readonly window: Window;
  readonly virtualConsole: VirtualConsole;
  readonly cookieJar: CookieJar;
  serialize(): string;
  nodeLocation(node: Node): LocationInfo | null | undefined;
  getInternalVMContext(): vm.Context;
  reconfigure(settings: ReconfigureSettings): void;
  static fragment(html: string): DocumentFragment;
  static fromURL(url: string, options?: FromURLOptions): Promise<JSDOM>;
  static fromFile(filename: string, options?: JSDOMOptions): Promise<JSDOM>;
}

Basic Usage:

// From HTML string
const dom = new JSDOM(`<!DOCTYPE html><p>Hello</p>`);

// From URL
const dom = await JSDOM.fromURL("https://example.com/");

// From file
const dom = await JSDOM.fromFile("./page.html");

// Create fragment (lightweight, no full browser environment)
const frag = JSDOM.fragment(`<p>Hello</p><p>World</p>`);

See JSDOM Constructor and Methods for complete API details.

Window Object

The Window object provides access to 180+ web standard interfaces:

// Access window from JSDOM instance
const window = dom.window;

// Window provides access to:
// - DOM APIs (Document, Element, Node, etc.)
// - HTML Elements (HTMLDivElement, HTMLInputElement, etc.)
// - Events (Event, MouseEvent, CustomEvent, etc.)
// - Storage (localStorage, sessionStorage)
// - Network (XMLHttpRequest, WebSocket, fetch Headers)
// - And 170+ more web standard interfaces

Usage Example:

const { document, Element, Event, localStorage } = dom.window;

// DOM manipulation
const div = document.createElement("div");
div.textContent = "Hello";
document.body.appendChild(div);

// Events
div.addEventListener("click", (e) => console.log("Clicked"));

// Storage
localStorage.setItem("key", "value");

See Window and DOM APIs for complete API reference.

Script Execution

Control how JavaScript executes within the jsdom environment:

interface JSDOMOptions {
  /**
   * Controls script execution
   * - undefined: Scripts don't execute (default)
   * - "outside-only": Enables window.eval() and fresh globals
   * - "dangerously": Executes inline and external scripts (security risk!)
   */
  runScripts?: "dangerously" | "outside-only";
}

Usage:

// Default: No script execution
const dom1 = new JSDOM(`<script>console.log("won't run");</script>`);

// Outside-only: Use window.eval()
const dom2 = new JSDOM(``, { runScripts: "outside-only" });
dom2.window.eval('document.body.innerHTML = "<p>Hello</p>"');

// Dangerously: Inline scripts execute automatically
const dom3 = new JSDOM(`
  <script>document.body.innerHTML = "<p>Hello</p>";</script>
`, { runScripts: "dangerously" });

Resource Loading

Load external scripts, stylesheets, images, and iframes:

interface JSDOMOptions {
  resources?: "usable" | ResourceLoader;
}

class ResourceLoader {
  constructor(options?: ResourceLoaderOptions);
  fetch(url: string, options: FetchOptions): Promise<Buffer | null>;
}

Usage:

// Enable resource loading
const dom = new JSDOM(`
  <script src="https://example.com/script.js"></script>
  <link rel="stylesheet" href="https://example.com/style.css">
`, {
  url: "https://example.org/",
  resources: "usable",
  runScripts: "dangerously"
});

// Custom resource loader
const loader = new ResourceLoader({
  proxy: "http://127.0.0.1:9001",
  userAgent: "MyApp/1.0"
});

See Resource Loading for complete details.

Virtual Console

Capture console output and jsdom errors:

class VirtualConsole {
  constructor();
  forwardTo(console: Console, options?: ForwardOptions): this;
  on(event: ConsoleMethod, listener: (...args: any[]) => void): this;
  on(event: "jsdomError", listener: (error: JSDOMError) => void): this;
}

Usage:

const virtualConsole = new VirtualConsole();
virtualConsole.on("error", (err) => console.error("Page error:", err));
virtualConsole.on("jsdomError", (error) => {
  console.error("jsdom error:", error.type, error.message);
});

const dom = new JSDOM(html, { virtualConsole });

See Virtual Console for complete details.

Cookie Management

HTTP cookie storage and management:

class CookieJar extends toughCookie.CookieJar {
  constructor(store?: toughCookie.Store, options?: CookieJarOptions);
}

Usage:

const cookieJar = new CookieJar();
cookieJar.setCookieSync("session=abc123", "https://example.org/");

const dom = new JSDOM(``, {
  url: "https://example.org/",
  cookieJar
});

// Access cookies from page
console.log(dom.window.document.cookie); // "session=abc123"

See Cookie Management for complete details.

Constructor Options

interface JSDOMOptions {
  /**
   * Sets window.location, document.URL, and document.documentURI
   * Also affects relative URL resolution and same-origin checks
   * @default "about:blank"
   */
  url?: string;

  /**
   * Sets document.referrer
   * @default "" (empty string)
   */
  referrer?: string;

  /**
   * Document content type - affects parsing mode
   * Must be an HTML MIME type or XML MIME type
   * @default "text/html"
   */
  contentType?: string;

  /**
   * Preserves location info for nodeLocation() method
   * Also ensures correct line numbers in script stack traces
   * Cannot be used with XML content type
   * @default false
   */
  includeNodeLocations?: boolean;

  /**
   * Maximum size in code units for localStorage and sessionStorage
   * @default 5000000
   */
  storageQuota?: number;

  /**
   * Controls script execution
   * - undefined: Scripts don't execute (default)
   * - "outside-only": Enables window.eval() and fresh globals
   * - "dangerously": Executes inline and external scripts (security risk!)
   * @default undefined
   */
  runScripts?: "dangerously" | "outside-only";

  /**
   * Controls resource loading (scripts, stylesheets, images, iframes)
   * - undefined: No resources loaded (default)
   * - "usable": Loads usable resources
   * - ResourceLoader instance: Custom resource loading
   * @default undefined
   */
  resources?: "usable" | ResourceLoader;

  /**
   * Pretends to be rendering/displaying content
   * - Changes document.hidden to false
   * - Changes document.visibilityState to "visible"
   * - Enables requestAnimationFrame/cancelAnimationFrame
   * @default false
   */
  pretendToBeVisual?: boolean;

  /**
   * Custom virtual console for capturing output
   * @default new VirtualConsole().forwardTo(console)
   */
  virtualConsole?: VirtualConsole;

  /**
   * Cookie jar for HTTP cookie storage
   * @default new CookieJar()
   */
  cookieJar?: CookieJar;

  /**
   * Hook called before HTML parsing begins
   * Useful for adding shims or modifying the environment
   * @param window - The window object (not yet populated with DOM)
   */
  beforeParse?: (window: Window) => void;
}

Learning Path

Getting Started

New to jsdom? Start here:

Getting Started Guide - Basic concepts and first steps
Common Patterns - Practical examples for everyday tasks

Advanced Topics

Ready to dive deeper?

Advanced Features - Advanced configurations, limitations, and edge cases

API Reference

Complete API documentation for all components:

JSDOM Constructor and Methods - Complete constructor API, factory methods, and instance methods
Window and DOM APIs - All 180+ web standard interfaces available on the window object
Virtual Console - Console output capture and jsdom error handling
Resource Loading - Loading external resources and custom loaders
Cookie Management - HTTP cookie storage and management

Additional Exports

Tough Cookie Access

// Access to the tough-cookie module used by jsdom
import { toughCookie } from "jsdom";

// toughCookie is the complete tough-cookie module
// Provides advanced cookie utilities beyond CookieJar

Version

Files

tessl/npm-jsdom

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

jsdom

Quick Start

Package Information

Core Imports

Architecture Overview

Core API

JSDOM Class

Window Object

Script Execution

Resource Loading

Virtual Console

Cookie Management

Constructor Options

Learning Path

Getting Started

Advanced Topics

API Reference

Additional Exports

Tough Cookie Access

index.mddocs/