Skip to content

Web scraping with Cheerio in 2024

Cheerio is a fast, flexible, and feature-rich scraping library for Node.js. With Cheerio, you can easily load HTML, parse it, and extract data using a simple yet powerful API inspired by jQuery selectors.

In this comprehensive guide, we‘ll explore web scraping from start to finish using Cheerio in Node.js. We‘ll cover:

  • What is Cheerio and why use it
  • Setting up the Cheerio environment
  • Loading and parsing HTML
  • Using Cheerio selectors
  • Extracting and manipulating data
  • Handling dynamic content with Puppeteer
  • Writing scraped data to files
  • Overcoming common challenges like anti-scraping measures
  • Testing web scrapers with Jest
  • Best practices and alternatives

So if you‘re ready to master Cheerio web scraping in 2024, let‘s begin!

What is Cheerio and Why Use It?

Cheerio is a fast, flexible, and modular scraping library designed specifically for the server-side Node.js environment.

Here are some key advantages of using Cheerio:

  • jQuery-style syntax: The API is designed to mimic jQuery, making Cheerio easy to use for developers familiar with web dev.

  • Blazing fast: Cheerio works without a browser, allowing it to operate at Node.js speed.

  • Lightweight: Weighing in at only 6.6kb minified, it has a small footprint compared to browser testing frameworks.

  • Modular design: Built as a Node.js module, it can be extended and customized.

  • Intuitive API: A host of useful methods like .text(), .attr(), $.find() make manipulating HTML a breeze.

For most static websites and basic scraping needs, Cheerio provides an excellent balance of speed, flexibility, and ease of use. Let‘s see it in action next.

Setting Up the Cheerio Environment

To start using Cheerio for web scraping, we first need to set up a Node.js environment. Here are the steps:

1. Install Node.js

Head to and download the LTS version of Node.js for your operating system. Run the installer.

2. Initialize a Node project

Open your terminal/command prompt, navigate to a directory of your choice, and type:

npm init -y

This will create a package.json file with default configurations for your Node project.

3. Install Cheerio

Now install Cheerio by running:

npm install cheerio

This will install Cheerio and add it to your package.json file as a dependency.

And that‘s it! We now have a Node.js environment ready with the Cheerio library installed.

Loading and Parsing HTML with Cheerio

Let‘s start using Cheerio by loading some HTML. The load method allows us to parse HTML in two ways:

1. Load from a string

We can directly load HTML passed as a string:

// Import Cheerio
const cheerio = require(‘cheerio‘); 

// HTML string
const html = `
  <h2>Hello World</h2>
  <p>This is some paragraph text.</p> 

// Load HTML 
const $ = cheerio.load(html);

2. Load from a file

We can also load HTML from a local file:

const fs = require(‘fs‘);
const html = fs.readFileSync(‘index.html‘); 

const $ = cheerio.load(html);

This parses the HTML and allows us to manipulate it using Cheerio selectors and methods.

Using Cheerio Selectors

Cheerio selectors provide a jQuery-like interface for querying HTML and extracting data.

Some examples:

By tag:

const headings = $(‘h2‘); // Select all h2 elements

By class:

const paragraphs = $(‘.paragraph‘); // Select by class name

By attribute:

const inputs = $(‘input[name="first_name"]‘); // Inputs with specific name attribute

By type:

const submitButtons = $(‘input[type="submit"]‘);

And many more combinations are possible!

We can call .text() or .html() on selections to get their content as a string.

const firstParagraph = $(‘p‘).first().text(); // Returns text of first paragraph

This allows us to extract any data we want from the HTML using selectors.

Extracting and Manipulating Data

Now let‘s see how we can extract and format structured data from HTML using Cheerio:

// Sample HTML
const html = `
  <div class="book">
    <h2 class="title">The Great Gatsby</h2> 
    <p class="author">F. Scott Fitzgerald</p>
    <p class="description">The Great Gatsby is a 1925 novel by American writer F. Scott Fitzgerald.</p>

  <div class="book">
    <h2 class="title">To Kill a Mockingbird </h2>
    <p class="author">Harper Lee</p>
    <p class="description">To Kill a Mockingbird takes place in the fictional town of Maycomb, Alabama during the Great Depression.</p> 

// Load HTML
const $ = cheerio.load(html);

// Define data to extract
const books = []; 

$(‘.book‘).each((i, book) => {

  // Extract info from each book
  const title = $(book).find(‘.title‘).text();
  const author = $(book).find(‘.author‘).text();
  const description = $(book).find(‘.description‘).text();

  books[i] = {



    "title": "The Great Gatsby",
    "author": "F. Scott Fitzgerald",
    "title": "To Kill a Mockingbird",
    "author": "Harper Lee",

This allows us to extract data from HTML in a structured format ready for processing and storage. The true power of Cheerio lies in its concise yet versatile API for querying DOM elements.

Handling Dynamic Content with Puppeteer

A limitation of Cheerio is that it only processes static HTML, not JavaScript rendered content. To overcome this, we can use Puppeteer in combination with Cheerio.

Puppeteer is a Node library that provides a high-level API for controlling headless Chrome. Here‘s how we can use it with Cheerio:

1. Install Puppeteer

npm install puppeteer 

2. Launch a browser instance

const puppeteer = require(‘puppeteer‘);

const browser = await puppeteer.launch();
const page = await browser.newPage();

3. Navigate to the target page

await page.goto(‘‘); 

4. Extract rendered HTML

const html = await page.content();

5. Pass to Cheerio

const $ = cheerio.load(html);

Now we have the fully rendered HTML and can scrape it with Cheerio!

This browser automation process enables us to scrape complex, JavaScript-heavy sites. The possibilities are endless when combining Puppeteer and Cheerio.

Writing Scraped Data to Files

To store scraped data, we can write it to structured files like CSV or JSON. Here‘s an example saving books data to a JSON file with the Node fs module:

const fs = require(‘fs‘);

  Books data extracted and formatted with Cheerio 
const books = [
   "title": "The Great Gatsby",
   "author": "F. Scott Fitzgerald"
   "title": "To Kill a Mockingbird",
   "author": "Harper Lee"

const json = JSON.stringify(books);

fs.writeFile(‘books.json‘, json, ‘utf8‘, (err) => {
  if (err) {
  } else {
    console.log("JSON file has been saved."); 

We first stringify the data into valid JSON, then use fs.writeFile() to save it to a file on our filesystem.

This allows us to store scraped data efficiently for later processing and analysis. The data can also be inserted into databases and consumed by other applications.

Overcoming Common Challenges

Web scraping with Cheerio can pose challenges including:

Dynamic content – Cheerio itself can only parse static HTML. We can integrate Puppeteer as shown earlier to overcome this.

Large datasets – Memory management can become an issue when scraping large pages. We can process data in batches to handle large scrapes.

Anti-scraping measures – Many sites try to detect and block scrapers. Using proxies, spoofing headers, and implementing delays can help bypass protections.

Handling errors – Network errors, 404s, captchas, etc. need to be handled properly for scrapers to be robust. Try/catch blocks and retrying failed requests goes a long way.

While challenging, these issues can be overcome with intelligent strategies and persisting through the trials and errors of scraping.

Testing Web Scrapers with Jest

Testing is important to ensure our scrapers work correctly across various pages and scenarios.

Jest is a popular framework for testing JavaScript code. Let‘s see how to test a Cheerio scraper with Jest:

1. Install Jest

npm install --save-dev jest

2. Import scraper function

// books.js
import { getBookInfo } from ‘./scraper‘; 

// scraper.js
export const getBookInfo = (html) => {
  // Scraper implementation

3. Write test cases

// books.test.js

test(‘Extracts book info‘, () => {

  const html = `
    <div class="book">
      <h2 class="title">The Great Gatsby</h2>
      <p class="author">F. Scott Fitzgerald</p>

  const expected = {
    title: ‘The Great Gatsby‘,
    author: ‘F. Scott Fitzgerald‘  



4. Run tests

npm test

This allows us to verify our Cheerio scrapers by testing them against sample HTML. We can write multiple test cases with different inputs and expected outputs.

Best Practices

Here are some best practices to follow when writing scrapers in Cheerio:

  • Use proper CSS/DOM selectors to extract data rather than regex which can be brittle.

  • Break down complex selectors into simpler ones for readability and maintenance.

  • Validate and sanitize all extracted data – never trust it at face value.

  • Always test scrapers thoroughly across various pages and scenarios.

  • Implement a robust error handling strategy with try/catch blocks and retries.

  • Use tools like Puppeteer, proxies, and headers to bypass anti-scraping measures.

  • Rate limit requests to sites and implement delays to avoid overloading servers.

  • Follow a site‘s robots.txt and respect request limits to avoid blocks.

Adhering to best practices results in reliable, efficient, and production-ready scrapers.

Alternative Scraping Libraries

While Cheerio is a popular choice, here are some alternatives:

  • Puppeteer – Headless Chrome scraping and automation.
  • Playwright – Browser automation with cross-browser support.
  • Scrapy – Full-featured high-performance scraping framework for Python.
  • node-fetch – Simple HTTP request library for Node.js.
  • Axios – Promise based HTTP client for Node.js.

Each has their own strengths and tradeoffs. For simple scraping needs, Cheerio provides a lightweight yet powerful option.


Cheerio is a versatile scraping library that allows you to efficiently extract data from HTML using CSS selectors.

With Cheerio, you can parse HTML docs, select elements, extract text/attrs, loop through nodes, and more – all with concise jQuery-style syntax.

When combined with tools like Puppeteer, Cheerio enables you to scrape both static and dynamic websites from Node.js. Robust error handling and testing produces resilient web scrapers ready for the real world.

There is a learning curve to mastery as with any skill. But by starting out with the fundamentals in this guide, you‘re now equipped to build amazing scrapers with Cheerio.

The possibilities are endless once you gain confidence wielding this sharp tool. Scraping data is at your fingertips – so go out and gather some interesting information from the web!

Join the conversation

Your email address will not be published. Required fields are marked *