The Complete Production SOP: How to Deploy and Run Cheerio High-Speed HTML Parser & Scraping in Autonomous AI Agents

---
name: "cheerio-highspeed-html-parser"
description: "Parse, manipulate, and extract data from HTML strings at microsecond speed with Cheerio."
metadata:
  author: "Cheerio"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "parse html with cheerio"
  - "extract data from html nodejs"
  - "scrape web page cheerio"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Cheerio High-Speed HTML Parser & Scraping

Extracts structured data from server-rendered HTML using Cheerio (jQuery-like syntax in Node.js): CSS selectors, traversing DOM trees, extracting table matrices, and stripping boilerplate.

## Execution SOP & Rules
1. Load HTML using const $ = cheerio.load(htmlContent).
2. Extract text attributes cleanly with $(element).find('.title').text().trim().
3. Iterate over element sets with $('.item').map((i, el) => ({ ... })).get().
4. Prefer Cheerio over headless browsers when pages render data in initial server-side HTML.

{
  "dependencies": {
    "cheerio": "^1.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.11.0",
    "typescript": "^5.3.3"
  }
}

import * as cheerio from 'cheerio';

export interface ProductItem {
  id: string;
  name: string;
  price: number;
  inStock: boolean;
}

export function parseCatalog(html: string): ProductItem[] {
  const $ = cheerio.load(html);
  return $('.product-card').map((_, el) => {
    const node = $(el);
    const id = node.attr('data-sku') || '';
    const name = node.find('.product-title').text().trim();
    const rawPrice = node.find('.price-value').text().replace(/[^0-9.]/g, '');
    const inStock = !node.hasClass('out-of-stock');
    return {
      id,
      name,
      price: parseFloat(rawPrice) || 0,
      inStock
    };
  }).get();
}

import { parseCatalog } from './parser';
import assert from 'node:assert';

const mockHtml = `
  <div class="catalog">
    <div class="product-card" data-sku="SKU-001">
      <span class="product-title"> mechanical keyboard </span>
      <span class="price-value">$129.99</span>
    </div>
    <div class="product-card out-of-stock" data-sku="SKU-002">
      <span class="product-title">gaming mouse</span>
      <span class="price-value">$59.00</span>
    </div>
  </div>
`;

const results = parseCatalog(mockHtml);
assert.strictEqual(results.length, 2);
assert.strictEqual(results[0].name, 'mechanical keyboard');
assert.strictEqual(results[0].price, 129.99);
assert.strictEqual(results[0].inStock, true);
assert.strictEqual(results[1].inStock, false);
console.log('✅ Cheerio parser validation passed successfully.');