{"id":10757,"library":"dom-serialize","title":"DOM Node to String Serializer","description":"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.","status":"maintenance","version":"2.2.1","language":"javascript","source_language":"en","source_url":"git://github.com/webmodules/dom-serialize","tags":["javascript","browser","node","dom","serialize","string"],"install":[{"cmd":"npm install dom-serialize","lang":"bash","label":"npm"},{"cmd":"yarn add dom-serialize","lang":"bash","label":"yarn"},{"cmd":"pnpm add dom-serialize","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports a default function. Named imports like `{ serialize }` will not work.","wrong":"import { serialize } from 'dom-serialize';","symbol":"serialize","correct":"import serialize from 'dom-serialize';"},{"note":"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';`.","symbol":"serialize","correct":"const serialize = require('dom-serialize');"}],"quickstart":{"code":"const serialize = require('dom-serialize');\n\n// Example 1: Serializing a text node\nlet textNode = document.createTextNode('Hello & <World>!');\nconsole.log('Text Node:', serialize(textNode));\n\n// Example 2: Serializing a DOM element with nested content\nlet bodyElement = document.createElement('body');\nlet strongElement = document.createElement('strong');\nstrongElement.appendChild(document.createTextNode('This is strong text.'));\nbodyElement.appendChild(strongElement);\nconsole.log('DOM Element:', serialize(bodyElement));\n\n// Example 3: Custom serialization using the 'serialize' event\nbodyElement.firstChild.addEventListener('serialize', function (event) {\n  // Override the serialization for the 'strong' tag\n  event.detail.serialize = '[CUSTOM-STRONG]';\n}, false);\nconsole.log('Custom Event Serialization:', serialize(bodyElement));\n\n// Example 4: One-time custom serializer function\nconst customSerializedOutput = serialize(bodyElement, function (event) {\n  if (event.serializeTarget === bodyElement.firstChild) {\n    // For the first child (the 'strong' tag), output an ellipsis\n    event.detail.serialize = '...';\n  } else if (event.serializeTarget !== bodyElement) {\n    // Prevent serialization of any other child elements if present\n    event.preventDefault();\n  }\n});\nconsole.log('One-time Function Serialization:', customSerializedOutput);","lang":"javascript","description":"This quickstart demonstrates how to serialize various DOM nodes (text, elements) and implement custom serialization logic using both event listeners and one-time functions."},"warnings":[{"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.","message":"Custom 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Correct the typo in `event.detail.serialze` to `event.detail.serialize` when providing custom serialization values.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"maintenance","affected_versions":"<=2.2.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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;`","cause":"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.","error":"ReferenceError: document is not defined"},{"fix":"For ES Modules, use `import serialize from 'dom-serialize';`. For CommonJS, use `const serialize = require('dom-serialize');` to correctly import the default function.","cause":"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.","error":"TypeError: serialize is not a function"}],"ecosystem":"npm"}