@curefatih-jf/hdom

v0.1.3

Published

2 years ago

Happy DOM is a JavaScript implementation of a web browser without its graphical user interface. It includes many web standards from WHATWG DOM and HTML.

Downloads

0High
0Medium
0Low

curefatih-jf

jsdom dom browser custom elements web components html whatwg w3c

About

Happy DOM is a JavaScript implementation of a web browser without its graphical user interface. It includes many web standards from WHATWG DOM and HTML.

The goal of Happy DOM is to emulate enough of a web browser to be useful for testing, scraping web sites and server-side rendering.

Happy DOM focuses heavily on performance and can be used as an alternative to JSDOM.

DOM Features

Custom Elements (Web Components)
Shadow Root (Shadow DOM)
Declarative Shadow DOM
Mutation Observer
Tree Walker
Fetch

And much more..

Works With

Installation

npm install happy-dom

Usage

Basic Usage

A simple example of how you can use Happy DOM.

import { Window } from 'happy-dom';

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

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

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

container.appendChild(button);

// Outputs "<div class="container"><button></button></div>"
console.log(document.body.innerHTML);

VM Context

The default Window class is a VM context. A VM context will execute JavaScript code scoped within the context where the Window instance will be the global object.

import { Window } from 'happy-dom';

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

window.location.href = 'http://localhost:8080';

document.write(`
    <html>
        <head>
             <title>Test page</title>
        </head>
        <body>
             <div class="container">
                  <!–– Content will be added here -->
             </div>
            <script>
                const element = document.createElement('div');
                const container = document.querySelector('.container');
                element.innerHTML = 'Test';
                container.appendChild(element);
            </script>
        </body>
    </html>
`);

// Will output "Test"
console.log(document.querySelector('.container div').innerHTML);

Global Context

Happy DOM exports a class called GlobalWindow, which can be used to run Happy DOM in the global context instead of the default behaviour of running in a VM context.

import { Window, GlobalWindow } from 'happy-dom';

const vmWindow = new Window();
const globalWindow = new GlobalWindow();

// Will output "false"
console.log(vmWindow.Array === global.Array);

// Will output "true"
console.log(globalWindow.Array === global.Array);

globalWindow.eval('global.test = 1');

// Will output "1"
console.log(global.test);

Server-Side Rendering of Web Components

The example below will show you how to setup a Node VM context to render a page with custom elements (web components) in Happy DOM. We can then use a new web feature called Declarative Shadow DOM to include the shadow roots in the HTML output.

Declarative Shadow DOM is only supported by Chromium based browsers. Unsupported browsers should safely fallback to being rendered using Javascript.

import { Window } from 'happy-dom';

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

window.location.href = 'http://localhost:8080';

document.write(`
    <html>
        <head>
             <title>Test page</title>
        </head>
        <body>
            <div>
                <my-custom-element>
                    <span>Slotted content</span>
                </my-custom-element>
            </div>
            <script>
                class MyCustomElement extends HTMLElement {
                    constructor() {
                        super();
                        this.attachShadow({ mode: 'open' });
                    }

                    connectedCallback() {
                        this.shadowRoot.innerHTML = \`
                            <style>
                                :host {
                                    display: inline-block;
                                    background: red;
                                }
                            </style>
                            <div><slot></slot></div>
                        \`;
                    }
                }

                customElements.define('my-custom-element', MyCustomElement);
            </script>
        </body>
    </html>
`);

/*
Will output:
<my-custom-element>
    <span>Slotted content</span>
    <template shadowroot="open">
        <style>
            :host {
                display: inline-block;
                background: red;
            }
        </style>
        <div><slot></slot></div>
    </template>
</my-custom-element>
*/
console.log(document.body.querySelector('div').getInnerHTML({ includeShadowRoots: true }));

Additional Features

Happy DOM exposes two functions that may be useful when working with asynchrounous code.

whenAsyncComplete()

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

window.happyDOM.whenAsyncComplete().then(() => {
    // Do something when all async tasks are completed.
});

cancelAsync()

This method will cancel all running async tasks.

window.setTimeout(() => {
    // This timeout will be canceled
});
window.happyDOM.cancelAsync();

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.

Global Registration

Happy DOM provide with a package called @happy-dom/global-registrator that can register Happy DOM globally. It makes it possible to use Happy DOM for testing in a Node environment.