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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ import { parse } from 'parse5';
✗ const parse = require('parse5');
parse5 is primarily consumed as an ES module. While CommonJS `require` might work in some setups, it's not the recommended or future-proof approach for modern Node.js/browser environments.
parseFragment
✓ import { parseFragment } from 'parse5';
✗ import parseFragment from 'parse5/lib/parser/parse-fragment';
For parsing HTML fragments, `parseFragment` is the correct named export. Directly importing from internal paths is not stable across versions.
serialize
✓ import { serialize } from 'parse5';
✗ import { serializeToString } from 'parse5';
The primary serialization function is `serialize`. There isn't a separate `serializeToString` export in the main library.
ParserStream
✓ import { ParserStream } from 'parse5';
✗ import { ParserStream } from 'parse5/lib/parser-stream';
The `ParserStream` class for streaming HTML parsing is available directly from the top-level `parse5` package. Importing from specific sub-paths is not guaranteed.
DefaultTreeAdapter
✓ import { DefaultTreeAdapter } from 'parse5/lib/tree-adapters/default';
✗ import { DefaultTreeAdapter } from 'parse5';
Tree adapter implementations are typically imported from their specific sub-paths, as they are not part of the main `parse5` exports. This allows for custom tree adapter usage.
Demonstrates basic full document parsing, HTML fragment parsing, serialization, and the usage of the streaming parser.
import { parse, serialize, parseFragment } from 'parse5';
import { createReadStream } from 'fs';
import { ParserStream } from 'parse5';
// Example 1: Parsing a full HTML document
const htmlDoc = '<!DOCTYPE html><html><head><title>Test</title></head><body><h1>Hello</h1><p>World</p></body></html>';
const document = parse(htmlDoc);
console.log('Parsed Document Type:', document.nodeName); // #document
// Example 2: Parsing an HTML fragment
const htmlFragment = '<div><span>Fragment</span></div>';
const fragment = parseFragment(htmlFragment);
console.log('Parsed Fragment Node Name:', fragment.nodeName); // #document-fragment
// Example 3: Serializing a document back to HTML
const serializedHtml = serialize(document);
console.log('Serialized HTML:', serializedHtml);
// Example 4: Using ParserStream for large files (simplified example)
const largeHtmlFilePath = 'some-large-file.html'; // Replace with a real path if testing locally
const parserStream = new ParserStream();
// In a real scenario, you'd pipe a readable stream to parserStream
// For demonstration, we'll simulate a stream.
// For actual usage, createReadStream(largeHtmlFilePath).pipe(parserStream);
parserStream.write('<!DOCTYPE html><html><head></head><body>');
parserStream.write('<h1>Streaming</h1><p>Example</p>');
parserStream.end('</body></html>');
parserStream.on('finish', () => {
console.log('Stream Parsed Document Type:', parserStream.document.nodeName);
});
Errors
Common errors & fixes
TypeError: Cannot destructure property 'parse' of 'parse5__WEBPACK_IMPORTED_MODULE_0__' as it is undefined.
Incorrect import statement in a CommonJS context or when module resolution is misconfigured for ESM.
fixEnsure you are using `import { parse } from 'parse5';` for ESM. For older CommonJS environments (though not recommended for parse5 v7+), `const parse = require('parse5').parse;` might be needed, but migrating to ESM is preferred. Property 'someProperty' does not exist on type 'Document'.
Attempting to access properties specific to a `HTMLElement` (like `querySelector`) directly on the `Document` or `DocumentFragment` node returned by `parse` or `parseFragment` without type casting or checking node type.
fixTypeScript users should correctly narrow down the node type or cast it. Remember that `parse` returns a `Document` node and `parseFragment` returns a `DocumentFragment` node. You might need to traverse to child nodes to find `Element` types.
Error: `parse5-parser-stream` is not exported from `parse5`.
Attempting to import `ParserStream` or related streaming utilities from a deprecated or incorrect path.
fixAs of recent versions, `ParserStream` is directly exported from the main `parse5` package. Use `import { ParserStream } from 'parse5';`. Audit
Dependencies
entitiesrequiredUsed for decoding and encoding HTML entities during parsing and serialization.