happy-dom is a JavaScript implementation of a web browser without its graphical user interface, written in TypeScript, MIT-licensed, and built for developers who need a browser-like DOM inside Node.js or Bun instead of inside an actual browser window.

What it is

happy-dom is a TypeScript library that implements the browser's Document Object Model in pure JavaScript while leaving out the graphical user interface. It lives in the JavaScript and TypeScript ecosystem, carries an MIT licence, and shows 4,654 stars, 323 forks, and 444 open issues on GitHub, with the last push recorded on 12 September 2026. Instead of driving a real browser, it gives JavaScript code a document, elements, events, and supporting browser APIs that behave the way a browser would provide them.

The concrete problem it solves is testing and running front-end code without a browser. Components built with React, Vue, Svelte, Angular, Google LitElement, or lit-html depend on DOM APIs, Custom Elements, and Shadow DOM, none of which exist in a bare Node.js or Bun process. Rather than launching a real browser or a heavier headless environment, a developer substitutes happy-dom as the DOM that the code under test runs against. The environment it replaces is therefore the real browser or graphical browser session that would otherwise be required to unit-test DOM-dependent code.

Key capabilities

• Implements a browser DOM without the graphical user interface, exposing documents, elements, and browser APIs to JavaScript.
• Supports Custom Elements, the foundation of Web Components.
• Supports Declarative Shadow DOM.
• Implements Mutation Observer for reacting to DOM changes.
• Implements Tree Walker for traversing DOM nodes.
• Provides the Fetch API.
• Works with Vitest, Bun, Jest, Testing Library, Google LitElement, Vue, React, Svelte, and Angular.

Who uses it and how

• Front-end teams on React, Vue, Svelte, or Angular that render and query components in unit tests without starting a browser.
• Projects built on Google LitElement and lit-html that exercise Web Components, Custom Elements, and Declarative Shadow DOM in tests.
• Test suites running under Vitest, Jest, or Bun, where happy-dom supplies the DOM environment the runner uses.
• Developers writing assertions with Testing Library who need a live document to query against.
• Node.js and Bun codebases that call DOM and Fetch APIs outside a browser.

Getting started

Setup follows the project's Getting started and Setup as Test Environment documentation. That documentation configures the happy-dom package as the DOM environment for runners such as Vitest, Jest, and Bun.

How it compares

happy-dom stands alone in this registry; the provided facts list no competing browser-DOM implementation. The tools it names, including Vitest, Bun, Jest, Testing Library, Google LitElement, Vue, React, Svelte, and Angular, are integrations it works with rather than alternatives it replaces.

When to use it — and when not to

happy-dom is a library that runs inside the developer's own Node.js or Bun process, so there is no server, database, storage, or mail service to operate, and the MIT licence is explicit. It should not be chosen by teams that need real browser rendering, layout, or screenshots, because it deliberately has no graphical user interface. Two weaknesses are visible in the facts: the README defers most detail to external documentation, and the project carries 444 open issues, so adopters should expect to read upstream docs and track the issue list.