Linkedom is a lightweight, fast, and efficient library for working with DOM and HTML in Node.js environments. It provides a comprehensive set of APIs to manipulate and traverse the DOM, similar to what you would find in a browser environment.
DOM Manipulation
This feature allows you to parse HTML strings and manipulate the DOM elements. In this example, we parse an HTML string, select a div element by its ID, change its text content, and then output the modified HTML.
const { parseHTML } = require('linkedom');
const { document } = parseHTML('<html><body><div id="app"></div></body></html>');
const appDiv = document.getElementById('app');
appDiv.textContent = 'Hello, World!';
console.log(document.toString());Event Handling
Linkedom supports event handling similar to browser environments. This example demonstrates how to add an event listener to a button element and dispatch a click event programmatically.
const { parseHTML } = require('linkedom');
const { document, Event } = parseHTML('<html><body><button id="btn">Click me</button></body></html>');
const button = document.getElementById('btn');
button.addEventListener('click', () => console.log('Button clicked!'));
const event = new Event('click');
button.dispatchEvent(event);CSS Selector Queries
You can use CSS selectors to query elements in the DOM. This example shows how to select all list items with a specific class and log their text content.
const { parseHTML } = require('linkedom');
const { document } = parseHTML('<html><body><ul><li class="item">Item 1</li><li class="item">Item 2</li></ul></body></html>');
const items = document.querySelectorAll('.item');
items.forEach(item => console.log(item.textContent));jsdom is a popular library that simulates a browser environment in Node.js. It provides a full-featured DOM and HTML parser, making it suitable for testing and server-side rendering. Compared to linkedom, jsdom is more comprehensive but also heavier and slower.
Cheerio is a fast, flexible, and lean implementation of core jQuery designed specifically for the server. It parses HTML and XML documents and provides a jQuery-like API for DOM manipulation. Cheerio is lighter and faster than jsdom but does not support a full DOM environment like linkedom.
node-html-parser is a fast HTML parser that can parse and manipulate HTML documents. It is lightweight and efficient but does not provide a full DOM API like linkedom. It is suitable for simple HTML parsing and manipulation tasks.
Social Media Photo by JJ Ying on Unsplash
A triple-linked lists based DOM with the following goals:
import {DOMParser, parseHTML} from 'linkedom';
// Standard way: text/html, text/xml, image/svg+xml, etc...
// const document = (new DOMParser).parseFromString(html, 'text/html');
// Simplified way for HTML
const {
// note, these are *not* globals
window, document, customElements,
HTMLElement,
Event, CustomEvent
// other exports ..
} = parseHTML(`
<!doctype html>
<html lang="en">
<head>
<title>Hello SSR</title>
</head>
<body>
<form>
<input name="user">
<button>
Submit
</button>
</form>
</body>
</html>
`);
// builtin extends compatible too 👍
customElements.define('custom-element', class extends HTMLElement {
connectedCallback() {
console.log('it works 🥳');
}
});
document.body.appendChild(
document.createElement('custom-element')
);
document.toString();
// the SSR ready document
document.querySelectorAll('form, input[name], button');
// the NodeList of elements
// CSS Selector via CSSselect
This module is based on DOMParser API, hence it creates a new document each time new DOMParser().parseFromString(...) is invoked.
As there's no global pollution whatsoever, to retrieve classes and features associated to the document returned by parseFromString, you need to access its defaultView property, which is a special proxy that lets you get pseudo-global-but-not-global properties and classes.
Accordingly, to simulate new JSDOM(html).window behavior, you can use a tiny helper like the following one:
// facade to a generic JSDOM bootstrap
import {parseHTML} from 'linkedom';
function JSDOM(html) { return parseHTML(html).defaultView; }
// now you can do the same as you would with JSDOM
const {document} = new JSDOM('<h1>Hello LinkeDOM 👋</h1>').window;
All nodes are linked on both sides, and all elements consist of 2 nodes, also linked in between.
Attributes are always at the beginning of an element, while zero or more extra nodes can be found before the end.
A fragment is a special element without boundaries, or parent node.
Node: ← node →
Attr<Node>: ← attr → ↑ ownerElement?
Text<Node>: ← text → ↑ parentNode?
Comment<Node>: ← comment → ↑ parentNode?
Element<Node>: ← start ↔ end → ↑ parentNode?
Fragment<Element>: start ↔ end
Element example:
parentNode?
↑
├────────────────────────────────────────────┐
│ ↓
node? ← start → attr* → text* → comment* → element* → end → node?
↑ │
└────────────────────────────────────────────┘
Fragment example:
┌────────────────────────────────────────────┐
│ ↓
start → attr* → text* → comment* → element* → end
↑ │
└────────────────────────────────────────────┘
Moving N nodes from a container, being it either an Element or a Fragment, requires the following steps:
As result, there are no array operations, and no memory operations, and everything is kept in sync by updating a few properties, so that removing 3714 sparse <div> elements in a 12M document, as example, takes as little as 3ms, while appending a whole fragment takes close to 0ms.
Try npm run benchmark:html to see it yourself.
This structure also allows programs to avoid issues such as "Maximum call stack size exceeded" (basicHTML), or "JavaScript heap out of memory" crashes (JSDOM), thanks to its reduced usage of memory and zero stacks involved, hence scaling better from small to very big documents.
At this point, even if this module is ready to cache results when no mutations happen, and since repeated crawling is not a too common pattern, but it can always be cached in user-land, the core always crawl left to right or right to left so that it guarantees it's always in sync with the current DOM state.
This module parses, and works, only with the following nodeType:
ELEMENT_NODEATTRIBUTE_NODETEXT_NODECOMMENT_NODEDOCUMENT_NODEDOCUMENT_FRAGMENT_NODEEverything else, at least for the time being, is considered YAGNI, and it won't likely ever land in this project, as there's no goal to replicate deprecated features of this aged Web.
To run the benchmark locally, please follow these commands:
git clone https://github.com/WebReflection/linkedom.git
cd linkedom/test
npm i
cd ..
npm i
npm run benchmark
Following a couple of (outdated) benchmark results example.
FAQs
A triple-linked lists based DOM implementation
The npm package linkedom receives a total of 117,747 weekly downloads. As such, linkedom popularity was classified as popular.
We found that linkedom demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Newly introduced telemetry in devenv 1.4 sparked a backlash over privacy concerns, leading to the removal of its AI-powered feature after strong community pushback.
Security News
TC39 met in Seattle and advanced 9 JavaScript proposals, including three to Stage 4, introducing new features and enhancements for a future ECMAScript release.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.