Installation & Quick Start

Relevant source files

The following files were used as context for generating this wiki page:

• Readme.md
• package.json
• website/src/content/blog/2024-08-07-version-1.md
• src/cheerio.spec.ts
• src/index.spec.ts
• CONTRIBUTING.md

Cheerio is a fast, flexible, and elegant library designed for parsing and manipulating HTML and XML in Node.js and browser environments. It implements a subset of core jQuery, removing browser-specific inconsistencies to provide a clean API for server-side DOM manipulation and web scraping.

This guide covers the prerequisites, installation methods, and basic usage patterns required to integrate Cheerio into a project. It also highlights the shift in Cheerio 1.0 toward a "batteries included" approach, supporting diverse loading methods including streams and direct URL fetching.
Sources: Readme.md:1-5, Readme.md:47-55, website/src/content/blog/2024-08-07-version-1.md:8-13

Installation

Cheerio requires Node.js version 18.17 or higher. It can be installed using various package managers compatible with the Node.js ecosystem.

Package Manager Commands

Manager	Command
npm	npm install cheerio
bun	bun add cheerio
deno	deno install cheerio
yarn	yarn add cheerio

Sources: Readme.md:38-44, package.json:149-151, website/src/content/blog/2024-08-07-version-1.md:67-69

Project Integration

Cheerio supports both ECMAScript Modules (ESM) and CommonJS (CJS) environments.

Importing the Library

// ESM or TypeScript
import * as cheerio from 'cheerio';

// CommonJS
const cheerio = require('cheerio');

Sources: Readme.md:62-66, package.json:34-77

Version 1.0 Breaking Changes

Users upgrading to version 1.0 must note that the deprecated default Cheerio instance and static methods have been removed. Code must now explicitly load a document before performing operations.
Sources: website/src/content/blog/2024-08-07-version-1.md:72-87

Quick Start: Loading and Manipulation

The core workflow in Cheerio involves three steps: loading markup, selecting/manipulating elements, and rendering the result.

Core Workflow Diagram

This diagram illustrates the standard data flow from raw input to manipulated output.
Sources: Readme.md:20-29, src/cheerio.spec.ts:46-55

Loading Methods

Cheerio 1.0 introduced specialized loading methods for different data sources:

Method	Purpose
load(content)	Standard method for parsing HTML or XML strings.
loadBuffer(buffer)	Parses binary data and automatically detects encoding.
stringStream()	Parses HTML directly from string streams.
decodeStream()	Parses HTML from binary streams.
fromURL(url)	Fetches and parses HTML from a URL in one operation.

Sources: website/src/content/blog/2024-08-07-version-1.md:22-29, src/index.spec.ts:32-38, src/index.spec.ts:108-112

Basic Usage Example

import * as cheerio from 'cheerio';

// 1. Load the document
const $ = cheerio.load('<h2 class="title">Hello world</h2>');

// 2. Select and manipulate
$('h2.title').text('Hello there!');
$('h2').addClass('welcome');

// 3. Render
const result = $.html();
//=> <html><head></head><body><h2 class="title welcome">Hello there!</h2></body></html>

Sources: Readme.md:20-29

Data Extraction

For complex data structures, the $.extract method provides a declarative way to map HTML elements to a JSON object.

Extraction Sequence

This diagram represents the internal logic of the extraction feature, which avoids manual loops for data mapping.
Sources: website/src/content/blog/2024-08-07-version-1.md:36-63, src/static.spec.ts:241-255

Extraction Snippet

const data = $.extract({
  releases: [
    {
      selector: 'section',
      value: {
        name: 'h2',
        date: {
          selector: 'relative-time',
          value: 'datetime',
        }
      },
    },
  ],
});

Sources: website/src/content/blog/2024-08-07-version-1.md:43-63

Summary

Setting up Cheerio involves installing the package via npm, bun, or deno and selecting the appropriate loading method for your data source. With the release of version 1.0, developers can utilize advanced features like fromURL for scraping and extract for structured data retrieval, while benefiting from the speed of a library that operates on a simplified DOM model without the overhead of a full browser environment.
Sources: Readme.md:47-55, website/src/content/blog/2024-08-07-version-1.md:8-13