# parse5: the HTML parser that other frameworks are built on

> A spec-compliant HTML parser and serializer for Node.js, written in TypeScript, maintained as a monorepo of small packages, and quiet enough that most of its users only know its name through jsdom, Cheerio, Angular or Lit.

**inikulin/parse5** — HTML parsing/serialization toolset for Node.js. WHATWG HTML Living Standard (aka HTML5)-compliant.

- Repository: https://github.com/inikulin/parse5
- Stars: 3,933 · Forks: 258
- Language: TypeScript
- License: MIT
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/inikulin-parse5

## What the README claims, and what it leaves out

The positioning in the README is direct. parse5 is described as an HTML parsing and serialization toolset for Node.js, compliant with the WHATWG HTML Living Standard, and the README calls it the fastest spec-compliant HTML parser for Node to date. The mechanism behind that speed claim is stated plainly as well: it parses HTML the way the latest version of your browser does, which is a statement about matching current browser behaviour rather than parsing faster than browsers do.

The credibility argument is a list of dependents. The README names jsdom, Angular, Lit, Cheerio and rehype as projects where it has proven reliable. That is the more useful half of the claim for an evaluator, because those are projects whose entire purpose is handling HTML written by other people.

What the README does not contain is worth noting too, because it shapes where you would actually start. There is no installation command, no usage snippet and no fenced code block anywhere in it. The body is centred HTML: a logo, badges for build status, npm version, monthly downloads, total downloads and coverage, then short paragraphs and a horizontal rule. The final section is a set of four links, one of which points to `docs/list-of-packages.md` described as the list of parse5 toolset packages, another to an online playground, and another to the changelog.

So the landing page tells you the project is large, compliant and fast, and then hands you off. That is a defensible choice for a library whose audience is other library authors, but it does mean the tree and the workspace manifest carry more of the explanatory load than usual.

## A monorepo where the root is tooling, not library code

The repository root contains no library source. Every top level entry is infrastructure: `.github/`, `.husky/`, `bench/`, `docs/`, `media/`, `scripts/`, `test/`, and a set of configuration files including `eslint.config.js`, `tsconfig.json`, `vitest.config.js`, `typedoc.json`, `typedoc.base.json`, `.prettierrc` and `.prettierignore`.

The code lives in `packages/`, which the workspace manifest declares as a glob rather than a list of names. The same manifest also folds `bench` and `test` in as workspaces, so the benchmark suite and the test suite are installed and built as part of the same dependency graph as the published code. That is a deliberate choice with a cost: a `node_modules` install for parse5 pulls the benchmark and test dependencies too.

The manifest identifies itself as `parse5-build-scripts` and is marked private, which confirms the root is a build and publishing workspace rather than something you would install. The publish step is a single command across workspaces:

```json
"build": "tsc --build packages/* test",
"publish": "npm publish --workspaces",
"unit-tests": "vitest run",
```

Two of those lines are worth pausing on. The build is a TypeScript project build, so the published artefacts are compiled from source rather than shipped as raw JS, and it covers the test workspace as well as the packages. Publishing fans out across every workspace at once, which is why the version bumps land in several packages together.

The `bench/` directory being a first class workspace is unusual and is the clearest sign that the speed claim in the README is meant to be checkable rather than rhetorical. There are dedicated benchmark scripts for throughput and for SAX parser memory use, and the performance script builds first so that benchmarks never run against stale output.

## Conformance is tested against html5lib, not hand written

The most interesting line in the manifest is the feedback test generator:

```json
"generate-feedback-tests": "node --loader ts-node/esm scripts/generate-parser-feedback-test/index.ts test/data/html5lib-tests/tree-construction/*.dat"
```

That single command points at the html5lib test corpus, specifically the `tree-construction` data files, and it runs through `scripts/generate-parser-feedback-test/index.ts`. The mechanism is worth spelling out because it explains how a parser stays compliant with a specification that has no final version.

The WHATWG HTML Living Standard changes continuously, and the html5lib corpus is updated to match. Rather than transcribing each new expectation into a test file by hand, this generator reads the `.dat` files and produces test cases from them. When the standard changes, the corpus changes, the generator is re-run, and the resulting failures point at exactly which tree construction behaviour drifted. A parser that passes this suite has not been proven correct, but it has been measured against the reference corpus, which is a stronger claim than a set of hand written examples.

Two details support the setup. The generator runs under `ts-node/esm`, meaning the tooling itself is TypeScript compiled on the fly rather than prebuilt, so a contributor can change the generator and immediately regenerate. And the presence of `.gitmodules` alongside `test/data/` indicates the html5lib corpus is pulled in as a git submodule rather than vendored, which is how a large external corpus is normally kept in sync without bloating this repository's own history.

There is a matching verification story. The manifest wires `test` to run linting first and unit tests second, coverage runs through `vitest run --coverage` with the v8 provider, and the README carries a Coveralls badge reporting coverage on `master`. The build badge points at a GitHub Actions workflow named `nodejs-test.yml`, and CodeQL appears in the release history, so static analysis is part of the pipeline too.

## Toolchain choices that say something about the maintainer

The development dependencies are a readable statement of how this project is worked on. The test runner is Vitest, and the release notes for v7.3.0 include a migration to Vitest, which means the move off an older runner was a considered step rather than a fresh start.

Formatting and linting are both present, and both are strict. Prettier handles formatting for JavaScript, TypeScript, Markdown, JSON and YAML. ESLint runs on top with `@eslint/js`, `typescript-eslint` and a plugin named `eslint-plugin-unicorn-x`. The v7.3.0 notes also record `no-explicit-any` being promoted to an error level, which is a small detail with a large meaning in a codebase whose whole job is turning untyped markup into a typed tree. An `outdent` dependency suggests template literals are used to build expected fixtures or documentation snippets.

Git hooks are enforced rather than suggested. `husky` is installed through a `prepare` script, and `nano-staged` is wired to a `pre-commit` script, so staged files are formatted on commit instead of relying on a contributor to remember. Documentation is generated with TypeDoc, and the two `typedoc` config files, one base and one per project, suggest the packages are documented together with per-package overrides. `prettier` also has a check mode in the lint chain, so an unformatted file fails the same command that runs the tests.

The observable effect is that a pull request has to satisfy formatting, linting, type checking and tests in one pass. That is a heavier gate than many projects would choose, and it is consistent with a library whose consumers are large frameworks where a subtle behaviour change is expensive to detect downstream.

## Release history: dependency bumps, and one major line

Three releases are visible in this snapshot, and their shape tells you where the effort goes. v8.0.0 in July 2025 is the major version bump. Its notes are a list of Dependabot pull requests: `codeql-action` from 3.28.15 to 3.28.16, `eslint-plugin-unicorn` from 58.0.0 to 59.0.0, and `typescript-eslint` from 8.31.0 to 8.31.1. v8.0.1 in April 2026 continues the same pattern with dev dependency bumps to `@eslint/js`, `eslint` and `typescript-eslint`.

Read together, those notes say something worth stating plainly. When this project ships a release, it is usually shipping updated tooling rather than new parser behaviour. The most interesting entry in the whole set is v7.3.0 in April 2025, and even that is mostly infrastructure: bump dependencies, upgrade the entities package, promote `no-explicit-any` to an error, migrate to Vitest, and fix broken links to the documentation. The documentation link fix is credited to a named contributor and the Vitest migration to another, so outside contributions are landing on real maintenance tasks.

The numbers describe a project with a settled audience rather than a growing one. At 3,933 stars and 258 forks it is well established, and 39 open issues is a low ratio for a project that size. The last push in this snapshot is September 2026, which is recent enough to say the repository is being worked on now.

What is missing from the visible surface is as informative as what is present. A `SECURITY.md` is present but no `CONTRIBUTING.md`, so there is a published route for reporting a vulnerability and no published route for outside contributors beyond the credits in the release notes. There is also no changelog file in the tree, even though the README links to one, which tells you the release notes on the releases page serve that role. The license is MIT. There is no `AUTHORS` file and no governance document, which fits a project maintained under a single owner account.

## Conclusion

parse5 is infrastructure in the literal sense. Its own README names jsdom, Angular, Lit, Cheerio and rehype as projects that have relied on it, which means a large share of the HTML handling in the JavaScript ecosystem is standing on this one package without the application author ever naming it.

The trade-offs follow from that position. Compliance is the priority, which means the parser reproduces the standard's error recovery rather than rejecting malformed input, so you should not expect a parse failure to tell you your markup was wrong. The output is a specification-shaped tree rather than a convenient one, so reading a value usually means walking from the document root. And the README is thin: this snapshot has no installation snippet, no usage example and no code fence at all, so the practical entry point is the package list under `docs/` and the typed documentation rather than the landing page.

What the repository does show well is the shape of the work. The workspace root holds tooling, not code, with the actual packages under `packages/`, and the test suite is generated against the html5lib corpus rather than hand written, which is the honest way to claim conformance to a specification that changes continuously.

## FAQ

### What is parse5?

parse5 is described in its README as an HTML parsing and serialization toolset for Node.js that is compliant with the WHATWG HTML Living Standard, also known as HTML5. It is written in TypeScript, published from a monorepo of packages under `packages/`, and the README calls it the fastest spec-compliant HTML parser for Node to date.

### Which projects depend on parse5?

The README names jsdom, Angular, Lit, Cheerio and rehype as projects where parse5 has proven reliable, describing it as reliable in such projects as those and many more. Each of those is a project whose purpose involves handling HTML, so the claim is about behaviour under real markup rather than about benchmarks.

### How does parse5 verify that it is spec compliant?

Through the html5lib test corpus. The manifest defines a `generate-feedback-tests` script that reads the `tree-construction` `.dat` files under `test/data/html5lib-tests/` and turns them into test cases. The corpus tracks the Living Standard as it changes, so re-running the generator against an updated corpus surfaces parser behaviour that has drifted from the specification.

### What test runner and formatter does parse5 use?

Vitest, run through `vitest run` with the v8 coverage provider, and the v7.3.0 release notes record a migration to Vitest. Formatting is Prettier and linting is ESLint with `@eslint/js`, `typescript-eslint` and `eslint-plugin-unicorn-x`. The `test` script runs linting before unit tests, and `husky` with `nano-staged` formats staged files on commit.

### What license is parse5 released under?

MIT. The license file sits at the root of the repository alongside `SECURITY.md`, and no `AUTHORS` file or governance document appears in the tree listing, which is consistent with a project maintained under a single owner account.

## Sources

- [inikulin/parse5 on GitHub](https://github.com/inikulin/parse5)
- [Issues](https://github.com/inikulin/parse5/issues)
- [License: MIT](https://github.com/inikulin/parse5/blob/master/LICENSE)
- [README](https://github.com/inikulin/parse5/blob/master/README.md)
- [Releases](https://github.com/inikulin/parse5/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/inikulin-parse5