jsdom Deployment and Usage Guide

Prerequisites

Node.js: jsdom requires Node.js 16 or higher. Check the package.json "engines" field for specific version requirements.
npm: Version 7 or higher (comes with modern Node.js installations)
Operating System: Windows, macOS, or Linux

Installation

1. Clone the Repository

git clone https://github.com/jsdom/jsdom.git
cd jsdom

2. Install Dependencies

npm install

3. Verify Installation

npm test

This will run the test suite to ensure everything is working correctly.

Configuration

Basic Usage

The most common use case is creating a JSDOM instance:

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

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

Customizing jsdom

You can customize jsdom by passing options to the JSDOM constructor:

const dom = new JSDOM(``, {
  url: "https://example.org/",
  referrer: "https://example.com/",
  contentType: "text/html",
  includeNodeLocations: true,
  storageQuota: 10000000,
  runScripts: "dangerously"  // Only use with trusted content
});

Important Options:

url: Sets the base URL for the document (defaults to "about:blank")
referrer: Sets the referrer (defaults to empty string)
contentType: "text/html" or "application/xml" (defaults to "text/html")
includeNodeLocations: Preserves parser location info (defaults to false)
storageQuota: Maximum storage size in code units (defaults to 5,000,000)
runScripts: Set to "dangerously" to execute scripts (not recommended for untrusted content)

Loading Subresources

To load external resources (scripts, stylesheets):

const dom = new JSDOM(html, {
  resources: "usable",
  runScripts: "dangerously"
});

Build & Run

Development

npm run dev

This starts the development server with hot reloading.

Production

npm run build
npm start

The build script compiles the project for production, and start runs the production server.

Testing

npm test

Run the full test suite. You can also run specific test files:

npm test -- path/to/test-file.js

Deployment

Platform Recommendations

jsdom is a Node.js library, so deployment depends on your use case:

1. npm Package

If you're publishing jsdom as a dependency:

npm publish

2. Web Application

For applications using jsdom:

Vercel: Deploy Node.js applications with automatic scaling
Netlify: For SSR applications using jsdom
AWS Lambda: Package with your application code

3. Testing Environment

For CI/CD pipelines:

GitHub Actions: Use Node.js runners
CircleCI: Configure Node.js environment
Docker: Create a container with Node.js and jsdom

Docker Deployment

Create a Dockerfile:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

CMD ["node", "index.js"]

Build and run:

docker build -t my-jsdom-app .
docker run -p 3000:3000 my-jsdom-app

Troubleshooting

Common Issues

1. Node.js Version Compatibility

Error: Unsupported Node.js version

Solution: Ensure you're using Node.js 16 or higher. Check your version:

node --version

2. Script Execution Blocked

// When runScripts is not enabled
console.log(dom.window.document.getElementById("content").children.length); // 0

Solution: Enable script execution (only for trusted content):

const dom = new JSDOM(html, { runScripts: "dangerously" });

3. Relative URL Resolution Issues

// URLs not resolving correctly

Solution: Set the base URL:

const dom = new JSDOM(html, { url: "https://example.com/" });

4. Memory Issues with Large Documents

Solution: Adjust storage quota:

const dom = new JSDOM(html, { storageQuota: 20000000 });

5. XML Parsing Issues

// XML content not parsing correctly

Solution: Set content type to XML:

const dom = new JSDOM(xml, { contentType: "application/xml" });

Performance Tips

Reuse JSDOM instances when possible instead of creating new ones
Disable unnecessary features like includeNodeLocations if you don't need them
Use streaming for large documents when possible
Clean up after use to free memory:

dom.window.close();

Security Considerations

Never use runScripts: "dangerously" with untrusted content
Validate all input before processing with jsdom
Use appropriate content security policies when deploying applications
Keep dependencies updated to avoid known vulnerabilities

Debugging

Enable verbose logging:

const dom = new JSDOM(html, { virtualConsole: jsdom.createVirtualConsole().sendTo(console) });

Check for parser errors:

console.log(dom.window.document.querySelector("parsererror"));

How to Deploy & Use tmpvar/jsdom