Introduction & Features
Relevant source files
The following files were used as context for generating this wiki page:
Cheerio is a fast, flexible, and elegant library designed for parsing and manipulating HTML and XML documents. It is primarily built for server-side environments like Node.js, though it also supports browser environments. By implementing a subset of core jQuery, Cheerio provides a familiar and powerful API while removing browser-specific "cruft" and DOM inconsistencies, resulting in highly efficient performance.
The library acts as a wrapper around industrial-strength parsers, specifically parse5 for standard HTML and htmlparser2 for XML or forgiving HTML parsing. Unlike a full web browser, Cheerio does not execute scripts, evaluate CSS, or access the network (outside of specific helpers like fromURL), making it ideal for web scraping and server-side document transformation.
Sources: Readme.md:1-5, Readme.md:44-55, THREAT_MODEL.md:7-10
Core Philosophies & Architecture
Cheerio is built on three main pillars: proven syntax, speed, and flexibility. Its architecture focuses on a consistent internal DOM model that allows for blazingly fast manipulation compared to traditional JSDOM-based solutions.
Architecture Overview
The following diagram illustrates the high-level data flow within Cheerio when processing a document:
The workflow begins with raw input markup which is passed to the selected parser engine. The resulting internal DOM tree is then queried or modified via the Cheerio API.
Sources: Readme.md:44-55, THREAT_MODEL.md:7-10, src/parse.spec.ts:7-12
Key Features
| Feature | Description |
|---|---|
| Proven Syntax | Implements a subset of core jQuery for a gorgeous, familiar API. |
| Blazingly Fast | Efficient parsing and rendering due to a simple, consistent DOM model. |
| Flexible Parsing | Supports parse5 (HTML) and htmlparser2 (XML/HTML). |
| Environment Agnostic | Works in Node.js, browsers, Bun, and Deno. |
| Batteries Included | Version 1.0+ includes helpers for streaming, URL fetching, and data extraction. |
Sources: Readme.md:44-55, website/src/content/blog/2024-08-07-version-1.md:8-13
Technical Modules
Loading & Initialization
Before manipulation can occur, documents must be loaded into a Cheerio instance. Version 1.0 introduced several specialized loading methods to handle various data sources.
load(content, options): The standard method for parsing strings.loadBuffer(buffer): Tailored for binary data with automatic encoding detection.fromURL(url): A high-level helper usingundicito fetch and parse remote content.- Streaming APIs:
stringStreamanddecodeStreamfor direct stream processing.
Sources: website/src/content/blog/2024-08-07-version-1.md:21-31, Readme.md:65-74
The DOM Model
Cheerio collections consist of objects that mimic browser-based DOM nodes. These nodes define standard properties for traversal and inspection:
tagName,parentNode,previousSibling,nextSiblingnodeValue,firstChild,childNodes,lastChild
Sources: Readme.md:120-130, src/parse.spec.ts:258-278
Data Extraction Engine
The extract method is a significant feature in modern Cheerio versions, allowing developers to define a schema for pulling structured data from markup in a single call.
This diagram represents the sequence of operations during a call to the extract method.
Sources: website/src/content/blog/2024-08-07-version-1.md:38-70, src/static.spec.ts:223-239
Configuration & Environments
Cheerio is highly configurable via an options object passed during the load phase. Key configuration areas include:
| Option | Type | Description |
|---|---|---|
xml | Object/Boolean | Options for htmlparser2. Enables XML mode and specific parser behaviors. |
baseURI | String | Used to resolve relative links (href/src) when using .prop(). |
decodeEntities | Boolean | Whether to decode HTML entities (defaults to true). |
sourceCodeLocationInfo | Boolean | If true, nodes will include sourceCodeLocation metadata. |
Sources: website/src/content/blog/2024-08-07-version-1.md:88-93, src/api/attributes.spec.ts:213-228, src/cheerio.spec.ts:333-350, src/parse.spec.ts:358-368
Security & Threat Model
Cheerio maintains a strict security boundary by design. It treats all input markup and CSS selectors from external sources as untrusted.
In-Scope Vulnerabilities
- Denial of Service (DoS): Pathological input causing asymmetric CPU/Memory consumption (e.g., ReDoS).
- Prototype Pollution: Markup or API calls that modify
Object.prototype. - XSS Enablement: Incorrect escaping during serialization that makes output more dangerous than input.
Out-of-Scope
- Script Execution: Cheerio does not execute JavaScript found in
<script>tags. - Sanitization: Cheerio is not a sanitizer; users must use tools like
sanitize-htmlbefore rendering output in a browser.
Sources: THREAT_MODEL.md:12-45, SECURITY.md:52-64
Cheerio serves as a robust middleware for HTML/XML handling, prioritizing performance and API familiarity. By bridging the gap between raw parsing and high-level manipulation, it remains a standard tool for scraping, testing, and document transformation in the JavaScript ecosystem.