Registry / web-framework / node-html-better-parser

node-html-better-parser

library1.5.8jsnpmunverified

Node HTML Better Parser is a high-performance HTML parser for Node.js and TypeScript, currently at version 1.5.8 and last published 6 months ago. It serves as a fork of `fast-html-parser`, prioritizing speed to process large HTML files efficiently. It generates a simplified Document Object Model (DOM) and includes basic element query support. A key differentiator of this fork is its focus on providing a simpler API for editing HTML and its attributes, which was a primary motivation for its creation. While highly optimized for performance, it may not correctly parse all malformed HTML, though it handles common errors like missing closing tags for `<li>` or `<td>`. The library offers configurable options to retrieve content from `<script>`, `<style>`, `<pre>`, and comments, but users should note these options can slightly impact parsing performance.

web-framework serialization http-networking

npm install node-html-better-parser

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-HTML-BETTER-P

node-html-better-parser

web-frameworkjavascriptv1.5.8

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.

parse

✓ import { parse } from 'node-html-better-parser';

✗ const parse = require('node-html-better-parser').parse;

The primary function for parsing HTML. For TypeScript and modern Node.js, use named ESM import. CommonJS `require` is also supported, as shown in the README.

HTMLParser (CommonJS style)

✓ const HTMLParser = require('node-html-better-parser'); // then use HTMLParser.parse(data)

✗ import HTMLParser from 'node-html-better-parser';

This is the typical CommonJS `require` pattern where the module export is an object. In ESM, prefer named imports like `{ parse }`.

HTMLElement

✓ import { HTMLElement } from 'node-html-better-parser';

Import `HTMLElement` as a type for type annotations when working with parsed nodes, particularly in TypeScript.

This quickstart demonstrates parsing an HTML string, querying elements by ID and class, accessing their properties, retrieving script and style content using options, and modifying an element's content, then printing the resulting HTML.

import { parse } from 'node-html-better-parser'; const htmlString = '<!DOCTYPE html>\n<html lang="en">\n<head>\n <meta charset="UTF-8">\n <title>Sample Page</title>\n <style>body { font-family: sans-serif; }</style>\n</head>\n<body>\n <ul id="main-list">\n <li>Hello World</li>\n <li class="item">Another item</li>\n </ul>\n <script>console.log("script content");</script>\n</body>\n</html>'; // Parse the HTML, enabling script and style content retrieval const root = parse(htmlString, { script: true, style: true }); // Access the root node's children (the <html> tag in this case) console.log('Root children structure:', root.firstChild?.structure); // Query for an element by ID const mainList = root.querySelector('#main-list'); if (mainList) { console.log('\nFound #main-list:'); console.log(' Tag Name:', mainList.tagName); console.log(' Raw Attributes:', mainList.rawAttrs); console.log(' Text Content:', mainList.text); // Edit content of the list mainList.set_content('<li>New first item</li><li>New second item</li>'); console.log('\nList after set_content:', mainList.toString()); } // Query for an element by class name const item = root.querySelector('.item'); // Note: This will find 'Another item' before set_content if (item) { console.log('\nFirst element with class "item":', item.toString()); } // Get the content of the script tag const scriptTag = root.querySelector('script'); if (scriptTag) { console.log('\nScript Content:', scriptTag.text); } console.log('\nFull modified HTML:', root.toString());

Debug

Known issues

gotchaNode HTML Better Parser prioritizes performance, meaning some highly malformed HTML might not be parsed correctly, although it handles common HTML4-style errors (e.g., unclosed `<li>` or `<td>` tags). Always validate input if robustness against arbitrary malformed HTML is critical.

fix

Ensure input HTML is as well-formed as possible. For highly unpredictable or malicious HTML, consider pre-processing or using a more robust, but potentially slower, parser that aims for W3C compliance like `parse5`.

affects: >=1.0.0

gotchaEnabling certain parsing options (like `lowerCaseTagName`, `script`, `style`, `pre`, or `comment`) can significantly hurt performance. `lowerCaseTagName` is noted to hurt performance heavily, while others slightly impact it.

fix

Only enable parsing options (e.g., `script: true`, `style: true`) if you explicitly need to retrieve their content. Avoid `lowerCaseTagName` unless strictly necessary for your application's logic.

affects: >=1.0.0

gotchaThe `text` property of an `HTMLElement` is described as 'slow for the first time'. This implies an internal caching mechanism that incurs a performance hit on the initial access.

fix

If frequently accessing `text`, be aware of the initial performance cost. For operations requiring the raw, unescaped text content, use `text`. If performance is paramount and escaped text is acceptable, `rawText` might be more suitable or pre-calculate `text` once if needed repeatedly.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: parse is not a function

Attempting to use `parse` with an incorrect import statement, often when mixing CommonJS `require` with an ESM named import expectation, or vice-versa, or trying to use `require('pkg')` directly as a function.

fix

For ESM, use `import { parse } from 'node-html-better-parser';`. For CommonJS, use `const HTMLParser = require('node-html-better-parser');` and then `HTMLParser.parse(html)`. Do not use `const { parse } = require('node-html-better-parser');` directly if the module's main export is not a direct object with a `parse` property when using CommonJS (though for this library, it usually works).

TypeError: Cannot read properties of undefined (reading 'querySelector')

This typically occurs when `querySelector` is called on a `null` or `undefined` object, often because the `parse` function returned an empty or unexpected root, or a preceding `querySelector` failed to find a matching element.

fix

Always check the return value of `parse` and `querySelector` calls. The `parse` function returns a fictive root node. Access its children via `root.childNodes` or `root.firstChild` to ensure you're querying actual HTML elements. For example, `const root = parse(html); if (root && root.querySelector) { /* ... */ }`.

Upgrade

Version history

1.5.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Sharcoux/node-html-parser ↗

packagehttps://www.npmjs.com/package/node-html-better-parser ↗