Registry / serialization / dom-serialize

dom-serialize

JSON →
library2.2.1jsnpmunverified

dom-serialize is a JavaScript library designed to convert various types of DOM nodes into an HTML string representation. Unlike the standard `outerHTML` property, it provides robust serialization capabilities for a broader range of DOM entities, including DOM elements, text nodes, attribute nodes, comment nodes, documents, document fragments, doctypes, NodeLists, and arrays of nodes. The current stable version is 2.2.1, released approximately 10 years ago, suggesting a mature and stable, though not actively developed, state. A key differentiator is its extensible serialization logic through a custom 'serialize' event, allowing developers to intercept and override default serialization for specific nodes or even use a one-time serializer function. This provides fine-grained control over the output, making it suitable for scenarios requiring custom HTML generation or specific content filtering. It supports both browser and Node.js environments, though Node.js usage requires a virtual DOM implementation.

serialization
npm install dom-serialize
github ↗package ↗
INSTALL
IMPORT
SIG · DOM-SERIALIZE
D
dom-serialize
serializationjavascriptv2.2.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

serialize
✓ import serialize from 'dom-serialize';
✗ import { serialize } from 'dom-serialize';
The library exports a default function. Named imports like `{ serialize }` will not work.
serialize
✓ const serialize = require('dom-serialize');
This is the CommonJS `require` syntax, commonly used in Node.js environments. ES Modules can import CJS default exports using `import serialize from 'dom-serialize';`.

This quickstart demonstrates how to serialize various DOM nodes (text, elements) and implement custom serialization logic using both event listeners and one-time functions.

const serialize = require('dom-serialize'); // Example 1: Serializing a text node let textNode = document.createTextNode('Hello & <World>!'); console.log('Text Node:', serialize(textNode)); // Example 2: Serializing a DOM element with nested content let bodyElement = document.createElement('body'); let strongElement = document.createElement('strong'); strongElement.appendChild(document.createTextNode('This is strong text.')); bodyElement.appendChild(strongElement); console.log('DOM Element:', serialize(bodyElement)); // Example 3: Custom serialization using the 'serialize' event bodyElement.firstChild.addEventListener('serialize', function (event) { // Override the serialization for the 'strong' tag event.detail.serialize = '[CUSTOM-STRONG]'; }, false); console.log('Custom Event Serialization:', serialize(bodyElement)); // Example 4: One-time custom serializer function const customSerializedOutput = serialize(bodyElement, function (event) { if (event.serializeTarget === bodyElement.firstChild) { // For the first child (the 'strong' tag), output an ellipsis event.detail.serialize = '...'; } else if (event.serializeTarget !== bodyElement) { // Prevent serialization of any other child elements if present event.preventDefault(); } }); console.log('One-time Function Serialization:', customSerializedOutput);
Debug
Known issues
gotchaCustom serialization via the 'serialize' event bubbles up the DOM tree. An event listener on a parent node can inadvertently intercept and override serialization for its children. Always check `event.serializeTarget` to ensure you're modifying the intended node's serialization.
fix
When using the 'serialize' event, always check `event.serializeTarget` against the specific node you intend to customize, or use `event.stopPropagation()` if appropriate, to prevent unintended overrides.
affects: >=1.0.0
gotchaThe README example contains a typo when setting the custom serialization value: `event.detail.serialze = '…'` should be `event.detail.serialize = '…'`. Using the misspelled property will result in the custom serialization being ignored.
fix
Correct the typo in `event.detail.serialze` to `event.detail.serialize` when providing custom serialization values.
affects: >=1.0.0
gotchaWhen using `dom-serialize` in a Node.js environment, a global DOM implementation (like `document`) is not available by default. Direct DOM manipulation (e.g., `document.createElement`) will fail without a virtual DOM library.
fix
In Node.js, use a library such as `jsdom` to set up a virtual DOM environment before creating or manipulating DOM nodes that `dom-serialize` will process.
affects: >=1.0.0
maintenanceThe `dom-serialize` package has not seen active development or releases in approximately 10 years, with its latest version 2.2.1 published in November 2015. While stable, it may not receive updates for new DOM features, security vulnerabilities, or modern JavaScript syntax/module systems.
fix
Assess the suitability of this library for new projects requiring active maintenance or modern browser/Node.js features. Consider alternatives like `@quatico/dom-serializer` or `dom-serializer` (from CheerioJS) if active development, ESM support, or specific features like Shadow DOM serialization are needed.
affects: <=2.2.1
Errors
Common errors & fixes
ReferenceError: document is not defined
Attempting to create or manipulate DOM nodes (e.g., `document.createElement`, `document.createTextNode`) in a non-browser environment like Node.js without a virtual DOM.
fix
Install and configure a virtual DOM library like `jsdom`. For example: `const { JSDOM } = require('jsdom'); const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>'); global.document = dom.window.document;`
TypeError: serialize is not a function
The `dom-serialize` library exports its main function as a default export. This error typically occurs when attempting to use named imports (`import { serialize } from 'dom-serialize';`) or incorrectly destructuring the `require` call.
fix
For ES Modules, use `import serialize from 'dom-serialize';`. For CommonJS, use `const serialize = require('dom-serialize');` to correctly import the default function.
Upgrade
Version history
2.2.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/webmodules/dom-serialize ↗
packagehttps://www.npmjs.com/package/dom-serialize ↗
dom-serialize — npm install dom-serialize · libregistry