Upgrading to Cheerio 1.0
Relevant source files
The following files were used as context for generating this wiki page:
Cheerio 1.0 represents a significant milestone in the project's evolution, moving from long-standing release candidates to a stable version characterized by a "batteries included" philosophy. This release streamlines the API for modern JavaScript environments, improves data extraction capabilities, and simplifies document loading workflows.
The upgrade process involves addressing breaking changes such as the removal of legacy static methods, updated environment requirements, and a reorganized configuration structure. Developers must transition from the deprecated default Cheerio instance to a workflow that explicitly loads documents before manipulation.
Sources: website/src/content/blog/2024-08-07-version-1.md:1-12, Readme.md:40-52
Environment and Dependency Requirements
Cheerio 1.0 increases the minimum runtime requirements to support modern Node.js features and improves internal performance through updated dependencies.
| Requirement | Value / Change |
|---|---|
| Minimum Node.js Version | 18.17 or higher |
| Primary Parser | parse5 (default) |
| Optional Parser | htmlparser2 (via xml key) |
| DOM Types | Must be imported from domhandler |
Sources: website/src/content/blog/2024-08-07-version-1.md:65-85, package.json:140-155
Installation
To upgrade to the latest stable version, use the standard package manager commands:
npm install cheerio@latest
# or
bun add cheerio
# or
deno install cheerio
Sources: website/src/content/blog/2024-08-07-version-1.md:87-91, Readme.md:30-36
Core API Changes and Deprecations
The most significant architectural change is the removal of the deprecated default Cheerio instance and its static methods. All document interactions must now begin with a loading method to create a bound instance.
Removal of Static Methods
Legacy code that invoked methods like html(), text(), or xml() directly from the main cheerio import will no longer function. These methods are now bound to the instance returned by load.
The diagram shows the transition from direct static method calls to instance-based method calls.
| Deprecated Static Call | Modern Replacement |
|---|---|
cheerio.html(selector) | cheerio.load(html).html() |
cheerio.text(selector) | cheerio.load(html).text() |
cheerio.xml() | cheerio.load(html, {xml: true}).xml() |
Sources: website/src/content/blog/2024-08-07-version-1.md:68-80, src/tests/deprecated.spec.ts:130-220
Configuration Key Changes
Configuration options for htmlparser2 have been consolidated. Previously spread across the options object, they must now reside exclusively under the xml key.
// Cheerio 1.0 Configuration
const $ = cheerio.load('<html>', {
xml: {
withStartIndices: true,
decodeEntities: false
},
});
Sources: website/src/content/blog/2024-08-07-version-1.md:81-85, src/cheerio.spec.ts:245-255
Enhanced Document Loading
Cheerio 1.0 introduces specialized loading methods to handle various input formats, including streams and remote URLs, which were previously handled through external boilerplate.
Workflow for various loading methods available in Cheerio 1.0.
loadBuffer: Automatically detects document encoding from binary data.stringStream/decodeStream: Allows parsing directly from readable streams.fromURL: Fetches and parses a document in a single asynchronous call usingundici.
Sources: website/src/content/blog/2024-08-07-version-1.md:20-30, src/index.spec.ts:25-50, src/index.spec.ts:105-125
Data Extraction API
A new extract method simplifies the retrieval of structured data from a document, replacing manual traversal with a declarative schema.
Schema Structure
The extract method accepts an object where keys represent the desired output property and values define the selector and the value to extract (e.g., textContent, innerHTML, or an attribute name).
const data = $.extract({
items: [
{
selector: 'li',
value: {
name: '.name',
link: {
selector: 'a',
value: 'href',
},
},
},
],
});
Sources: website/src/content/blog/2024-08-07-version-1.md:32-60, src/static.spec.ts:210-225
Security and Maintenance
Cheerio 1.0 establishes a clear support lifecycle and security model. Version 1.x is the only branch receiving security updates; versions below 1.0 are officially unsupported.
Support Status
| Branch | Status |
|---|---|
| 1.x | ✅ Supported / Receiving Security Updates |
| < 1.0 | ❌ End of Life |
Sources: SECURITY.md:5-10, THREAT_MODEL.md:15-25
Upgrading to Cheerio 1.0 requires updating Node.js environments, refactoring static method calls into instance-based logic, and nesting parser options within the xml configuration object. These changes enable access to new streaming utilities and the powerful extract API.