or run

npx @tessl/cli init

Version

Files

docs

api

jsdom-constructor.md resource-loading.md virtual-console.md window-dom-apis.md

guides

advanced.md common-patterns.md getting-started.md

index.md

tile.json

Getting Started with jsdom

This guide covers the fundamental concepts and basic usage patterns for jsdom.

Basic Concepts

What is jsdom?

jsdom creates a browser-like environment in Node.js, providing:

A complete DOM implementation
180+ web standard interfaces
Script execution capabilities
Resource loading
Cookie management

Creating Your First DOM

The simplest way to create a DOM instance:

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

const dom = new JSDOM(`<!DOCTYPE html><p>Hello world</p>`);
const paragraph = dom.window.document.querySelector("p");
console.log(paragraph.textContent); // "Hello world"

Accessing the Window Object

The window object is your gateway to all browser APIs:

const { JSDOM } = require("jsdom");
const dom = new JSDOM(`<!DOCTYPE html><body></body>`);

// Access window directly
const window = dom.window;

// Or use destructuring
const { document, Element, Event, localStorage } = dom.window;

Common Initial Tasks

Creating Elements

const { JSDOM } = require("jsdom");
const dom = new JSDOM(`<!DOCTYPE html><body></body>`);
const { document } = dom.window;

// Create and append elements
const div = document.createElement("div");
div.id = "main";
div.className = "container";
div.textContent = "Hello World";
document.body.appendChild(div);

Querying Elements

const { JSDOM } = require("jsdom");
const dom = new JSDOM(`
  <!DOCTYPE html>
  <body>
    <div id="main" class="container">
      <p>Hello</p>
      <p>World</p>
    </div>
  </body>
`);

const { document } = dom.window;

// Get element by ID
const main = document.getElementById("main");

// Query selectors
const paragraphs = document.querySelectorAll("p");
const firstP = document.querySelector("p");

// Get elements by class
const containers = document.getElementsByClassName("container");

Modifying Content

const { JSDOM } = require("jsdom");
const dom = new JSDOM(`<!DOCTYPE html><body><p>Original</p></body>`);
const { document } = dom.window;

const p = document.querySelector("p");

// Change text content
p.textContent = "Updated text";

// Change inner HTML
p.innerHTML = "<strong>Bold text</strong>";

// Modify attributes
p.setAttribute("class", "highlight");
p.id = "my-paragraph";

Working with Options

Setting a URL

The url option is important for relative URL resolution:

const dom = new JSDOM(`<!DOCTYPE html><body></body>`, {
  url: "https://example.org/"
});

console.log(dom.window.location.href); // "https://example.org/"

Content Type

Control how the document is parsed:

// HTML parsing (default)
const dom1 = new JSDOM(`<!DOCTYPE html><p>Hello</p>`, {
  contentType: "text/html"
});

// XML parsing
const dom2 = new JSDOM(`<root><item/></root>`, {
  contentType: "application/xml"
});

Referrer

Set the document referrer:

const dom = new JSDOM(`<!DOCTYPE html><body></body>`, {
  url: "https://example.org/",
  referrer: "https://google.com/"
});

console.log(dom.window.document.referrer); // "https://google.com/"

Creating from Different Sources

From HTML String

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

From URL

const dom = await JSDOM.fromURL("https://example.com/");
console.log(dom.window.document.title);

From File

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

Creating Fragments

For lightweight DOM manipulation without a full browser environment:

const frag = JSDOM.fragment(`<p>Hello</p><p>World</p>`);
console.log(frag.childNodes.length); // 2

Next Steps

Learn Common Patterns for practical examples
Explore Advanced Features for complex scenarios
Review the API Reference for complete details