Skip to content

Upgrading cheerio 0.22 to 1

Breaking0.22.0 → 1.2.0Breaking18Security1Platform2Deprecated1New23Changed21Fixed41Other96

Full comparisonBack to cheerio
BreakingUpgrade verdict

18 breaking changes and 2 platform requirement changes and a security fix.

In plain terms
  • You can no longer call the default export or static helpers like `html` directly; load a document first.
  • If you called Cheerio directly without loading a document first, you must now access it through `.default`.
  • Code that read a node's `root` property must now use `parent` to reach the root node.
  • Output no longer escapes non-ASCII characters automatically, so make sure you set the right content encoding.
Must act Top 5 of 22 that need code or config changes

Node.js requirement changed in 1.1.1: >= 0.6 → >=20.18.1.

Adds cheerio-select ^2.1.0, domhandler ^5.0.3, domutils ^3.2.2, encoding-sniffer ^0.2.1, parse5 ^7.3.0, parse5-htmlparser2-tree-adapter ^7.1.0, parse5-parser-stream ^7.1.2, undici ^7.19.0, whatwg-mimetype ^4.0.0.

Drops css-select, entities, lodash.assignin, lodash.bind, lodash.defaults, lodash.filter, lodash.flatten, lodash.foreach, lodash.map, lodash.merge, lodash.pick, lodash.reduce, lodash.reject, lodash.some.

Installs 22 packages in all (was 27).

Also installs iconv-lite, safer-buffer, whatwg-encoding.

No longer installs inherits, readable-stream, safe-buffer, string_decoder, util-deprecate.

Moves css-select 1.2.0 → 5.2.2, css-what 2.1.3 → 6.2.2, dom-serializer 0.1.1 → 2.0.0, domelementtype 1.3.1 → 2.3.0, domhandler 2.4.2 → 5.0.3, domutils 1.5.1 → 3.2.2, entities 1.1.2 → 4.5.0, 6.0.1, 7.0.1, htmlparser2 3.10.1 → 10.1.0, nth-check 1.0.2 → 2.1.1. Your build may pick other versions.

What you must change

Breaking18
Removes the deprecated default Cheerio instance and static methods.
cheeriohtmlcheerio.load()
1.0.0GitHub ReleaseSummarizedView source
Using the function exported by Cheerio directly now requires the default export.
requiredefaultload()
1.0.0-rc.9GitHub ReleaseSummarizedView source
Uses the parser's DOM without modifications, so nodes no longer have a root reference; the root node is referenced by parent.
rootparent
1.0.0-rc.4GitHub ReleaseSummarizedView source
Uses parse5 to serialize the DOM and no longer encodes non-ASCII characters by default; pass the appropriate content encoding.
1.0.0-rc.4GitHub ReleaseSummarizedView source
Changes the default parser to Parse5, which conforms to the HTML standard but does not support XML.
load
1.0.0-rc.2GitHub ReleaseSummarizedView source
Renames the useHtmlParser2 option.
useHtmlParser2
1.0.0-rc.2GitHub ReleaseSummarizedView source
Simplifies import paths, e.g. use cheerio/slim instead of cheerio/lib/slim.
cheerio/slimcheerio/lib/slim
1.0.0GitHub ReleaseSummarizedView source
Node types previously re-exported by Cheerio must now be imported directly from domhandler.
domhandler
1.0.0GitHub ReleaseSummarizedView source
htmlparser2 options now reside exclusively under the xml key.
cheerio.load()xmlwithStartIndices
1.0.0GitHub ReleaseSummarizedView source
Cheerio is now a dual CommonJS and ESM module, so deep imports fail in newer versions of Node.
1.0.0-rc.11GitHub ReleaseSummarizedView source
.text() again includes script and style contents; use .prop('innerText') for the old behavior.
.text().prop('innerText')
1.0.0-rc.11GitHub ReleaseSummarizedView source
TypeScript types inherited from upstream dependencies have changed, with Node types now using tagged unions.
1.0.0-rc.11GitHub ReleaseSummarizedView source
Fixes the ordering of output for several methods, including prevAll, prevUntil and parentsUntil, to match jQuery.
prevAllprevUntilparentsUntil
1.0.0-rc.6GitHub ReleaseSummarizedView source
Inherits stricter pseudo selectors from css-select@4.0.0, now in line with the HTML spec.
1.0.0-rc.6GitHub ReleaseSummarizedView source
Inherits case-insensitive attribute matching for some attributes from css-select@4.0.0, based on the HTML spec.
1.0.0-rc.6GitHub ReleaseSummarizedView source
In XML mode, all elements now have type 'tag'.
1.0.0-rc.6GitHub ReleaseSummarizedView source
Makes strings passed to load() be interpreted as full documents instead of document fragments.
load$.root()
1.0.0-rc.2GitHub ReleaseSummarizedView source
Changes the options format.
1.0.0-rc.2GitHub ReleaseSummarizedView source
Security1
Bumps cheerio-select to address npm advisory 1754.
cheerio-select
1.0.0-rc.10GitHub ReleaseSummarizedView source
Platform2
Raises the minimum Node.js version to 18.17 or higher.
1.0.0GitHub ReleaseSummarizedView source
After upgrading parse5, cheerio temporarily requires a minimum Node version of Node 6.
1.0.0-rc.4GitHub ReleaseSummarizedView source

Deprecations to plan for

Deprecated1
Using Cheerio's exported function directly is deprecated and may be removed in a future version.
load()
1.0.0-rc.9GitHub ReleaseSummarizedView source