happy-dom

What is happy-dom?

happy-dom is a fast and lightweight DOM implementation for Node.js. It is designed to be compatible with the browser's DOM API, making it useful for server-side rendering, testing, and other scenarios where a DOM is needed outside of a browser environment.

What are happy-dom's main functionalities?

DOM Manipulation

happy-dom allows you to create and manipulate DOM elements just like you would in a browser environment. This is useful for server-side rendering and testing.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

const div = document.createElement('div');
div.textContent = 'Hello, World!';
document.body.appendChild(div);

console.log(document.body.innerHTML); // <div>Hello, World!</div>

Event Handling

happy-dom supports event handling, allowing you to add event listeners and dispatch events. This is useful for testing event-driven code.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

const button = document.createElement('button');
button.textContent = 'Click me';
button.addEventListener('click', () => {
  console.log('Button clicked!');
});
document.body.appendChild(button);

// Simulate a click event
const event = new window.Event('click');
button.dispatchEvent(event); // Button clicked!

Querying DOM Elements

happy-dom allows you to query DOM elements using methods like `querySelector` and `querySelectorAll`. This is useful for selecting and manipulating specific elements in the DOM.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

document.body.innerHTML = '<div class="test">Hello</div><div class="test">World</div>';
const elements = document.querySelectorAll('.test');

console.log(elements.length); // 2
console.log(elements[0].textContent); // Hello
console.log(elements[1].textContent); // World

Other packages similar to happy-dom

jsdom

jsdom is another popular DOM implementation for Node.js. It provides a more complete and detailed implementation of the DOM and other web standards. However, it is generally slower and more resource-intensive compared to happy-dom.

cheerio

cheerio is a fast, flexible, and lean implementation of core jQuery designed specifically for the server. It is not a full DOM implementation but provides a subset of jQuery functionality for parsing and manipulating HTML. It is faster and more lightweight than jsdom but less feature-rich.

linkedom

linkedom is a lightweight and fast DOM implementation for Node.js. It aims to be a minimalistic alternative to jsdom, providing essential DOM functionalities with better performance. It is similar to happy-dom in terms of performance and use cases.

README

About

A JSDOM alternative with support for server side rendering of web components.

Happy DOM aim to support the most common functionality of a web browser.

DOM Features

• Custom Elements (Web Components)

• Shadow Root (Shadow DOM)

• Mutation Observer

• Tree Walker

• Fetch

And much more..

Works With

• Google LitHTML

• Google LitElement

• React

• Angular

• Vue

Installation

npm install happy-dom

Usage

Basic Usage

The example below will show you to Happy DOM can be used for rendering a page.

import { Window } from 'happy-dom';

const window = new Window();
const document = window.document;

document.body.innerHTML = '<div class="myContainer"></div>';

const myContainer = document.querySelector('.myContainer');
const button = document.createElement('button');

myContainer.appendChild(button);

// Outputs "<div class="myContainer"><button></button></div>"
console.log(myContainer.outerHTML);

VM Context

The example below will show you how to setup a Node VM context to render a page in Happy DOM. The VM context can set the Happy DOM window object to be the global object and allows executing code scoped within the context.

import { AsyncWindow } from 'happy-dom';
import VM from 'vm';

const window = VM.createContext(new AsyncWindow());
const document = window.document;
const html = `
    <html>
        <head>
             <title>Test page</title>
        </head>
        <body>
             <div class="myContainer">
                  <!–– Content will be added here -->
             </div>
        </body>
    </html>
`;
const script = new VM.Script(`
    const element = document.createElement('div');
    const myContainer = document.querySelector('.myContainer');
    element.innerHTML = 'Test';
    myContainer.appendChild(element);
`);

window.location.href = 'http://localhost:8080';
window.whenAsyncComplete().then(() => {
    const myContainer = document.querySelector('.myContainer div');

    // Will output "Test"
    console.log(myContainer.innerHTML);
});

script.runInContext(context);

document.write(html);

Window vs AsyncWindow

Happy DOM exports two window objects: "Window" and "AsyncWindow". Read more about the differences between them below.

Window

Has all the basic functionality of a DOM except for fetch(). This has been excluded to make it possible to use Happy DOM client side without the dependencies to server side Node packages.

AsyncWindow

AsyncWindow extends Window and adds support for fetch(). It also exposes two methods that are useful when working with asynchrounous code.

whenAsyncComplete()

Returns a Promise that is resolved when all async tasks has been completed.

cancelAsync()

This method will cancel all running async tasks.

Performance

Operation	JSDOM	Happy DOM
Import / Require	333 ms	45 ms
Parse HTML	256 ms	26 ms
Serialize HTML	65 ms	8 ms
Render custom element	214 ms	19 ms
querySelectorAll('tagname')	4.9 ms	0.7 ms
querySelectorAll('.class')	6.4 ms	3.7 ms
querySelectorAll('[attribute]')	4.0 ms	1.7 ms
querySelectorAll('[class~="name"]')	5.5 ms	2.9 ms
querySelectorAll(':nth-child(2n+1)')	10.4 ms	3.8 ms

See how the test was done here

Jest

Happy DOM provide with a package called @happy-dom/jest-environment that makes it possible to use Happy DOM with Jest.

Server Side Rendering

Happy DOM provide with a package called @happy-dom/server-rendering that makes the setup of server side rendering easier.