Cheerio

Cheerio implements a subset of core jQuery designed specifically for the server, giving Node.js and browser developers a familiar, expressive API for parsing, traversing, and manipulating HTML and XML documents without the overhead of a full browser environment. It wraps parse5 for spec-compliant parsing (with an optional forgiving htmlparser2 mode) and operates directly against a lightweight DOM model, making it dramatically faster than driving a real browser or headless DOM implementation for the same job.

Widely used as the parsing layer inside web scrapers, static site generators, RSS/feed processors, and server-side rendering pipelines, Cheerio is a foundational dependency across the JavaScript scraping and content-processing ecosystem. Version 1.x ships full TypeScript types, dual ESM/CommonJS builds, and a slim entry point for bundle-size-sensitive environments.

What You Get

• A cheerio.load() entry point that parses an HTML or XML string into a queryable, mutable document
• A jQuery-compatible subset of selector, traversal, and manipulation methods (.find(), .attr(), .text(), .html(), .css(), .each(), and more)
• Pluggable parsing backends — the spec-compliant parse5 parser by default, or the forgiving, faster htmlparser2 parser via the xmlMode and parser options
• First-class TypeScript types, dual ESM/CommonJS builds, and a cheerio/slim entry point for smaller bundles

Common Use Cases

• Scraping and extracting structured data from HTML pages fetched via fetch, undici, or another HTTP client
• Server-side templating and post-processing of HTML output before it’s sent to the client
• Parsing RSS/Atom feeds or other XML documents with xmlMode enabled
• Asserting against rendered HTML output in unit and integration tests

Under The Hood

Architecture Cheerio’s execution flow begins in src/load.ts, which normalizes CheerioOptions (src/options.ts) and hands the input HTML/XML string to a pluggable parser via src/parsers/parse5-adapter.ts (or htmlparser2 directly in xmlMode), producing a domhandler-based node tree. That tree is wrapped by src/cheerio.ts’s abstract Cheerio class, which mixes in six method modules — src/api/traversing.ts, manipulation.ts, attributes.ts, css.ts, forms.ts, and extract.ts — via a MethodsType intersection, so the public $ object is a static factory (src/static.ts) plus this composed instance prototype. Serialization back to a string goes through dom-serializer, and selector matching is delegated to the separate cheerio-select package (itself built on css-select), keeping selection, DOM representation, and rendering as cleanly separated concerns.

Tech Stack Cheerio is TypeScript-first, targeting ES2019 with Node16 module resolution per tsconfig.json, and depends on a small, well-factored set of single-purpose packages: parse5 plus parse5-htmlparser2-tree-adapter/parse5-parser-stream for spec-compliant parsing, htmlparser2 for the forgiving fallback, domhandler/domutils/dom-serializer for the DOM model, cheerio-select for CSS selector matching, encoding-sniffer and whatwg-mimetype for charset/MIME detection, and undici for the optional fromURL HTTP fetch. Builds are produced as dual ESM/CommonJS output (dist/esm, dist/commonjs) via the package.json exports map, with a browser-specific entry (index-browser.mts) and a dependency-light cheerio/slim build for bundle-conscious consumers.

Code Quality The src tree pairs nearly every module with a co-located .spec.ts file (14 spec files covering cheerio.ts, load.ts, parse.ts, options.ts, static.ts, utils.ts, and each src/api/.ts module), run via Vitest per vitest.config.ts, with Biome (biome.json) and an ESLint flat config (eslint.config.js) enforcing style. Public methods carry structured TSDoc comments with @example blocks (visible throughout src/load.ts and src/cheerio.ts), strict TypeScript is enabled project-wide (strict: true, isolatedDeclarations: true in tsconfig.json), and the project publishes a SECURITY.md/THREAT_MODEL.md/INCIDENT_RESPONSE.md trio — an unusually mature process footprint for a library of its size.

API Design Cheerio’s headline design choice is deliberately mirroring jQuery’s $(selector) API, so anyone with browser-jQuery experience is productive immediately — cheerio.load(html) returns a bound $ with .find(), .attr(), .text(), .css(), .each(), and more. Getting started requires only one line (const $ = cheerio.load(html)) with no configuration, while power users can opt into xmlMode, a custom parser, or the cheerio/slim build without touching core call sites — a low floor for beginners paired with enough surface area across six method modules for advanced DOM manipulation without boilerplate.