Instalação

Cheerio é uma implementação server-side do jQuery core projetada especificamente para ambientes Node.js. Este guia abrange todas as formas de instalar e configurar o Cheerio em seus projetos.

Instalação via Package Manager

npm

npm install cheerio

yarn

yarn add cheerio

pnpm

pnpm add cheerio

bun

bun add cheerio

Sintaxe de Importação

ESM (ES Modules) - Recomendado

import * as cheerio from 'cheerio';

// Load HTML and create a Cheerio instance
const $ = cheerio.load('<h2 class="title">Hello world</h2>');

// Manipulate elements
$('h2.title').text('Hello there!');
$('h2').addClass('welcome');

console.log($.html());
// => <html><head></head><body><h2 class="title welcome">Hello there!</h2></body></html>

CommonJS

const cheerio = require('cheerio');

const $ = cheerio.load('<h2 class="title">Hello world</h2>');
$('h2.title').text('Hello there!');

Importações Desestruturadas

// Import specific functions
import { load, contains, merge } from 'cheerio';

const $ = load('<ul><li>Apple</li><li>Orange</li></ul>');

Configuração TypeScript

O Cheerio já vem com definições TypeScript integradas. Não é necessário um package @types adicional.

Uso Básico com TypeScript

import * as cheerio from 'cheerio';
import type { CheerioAPI, Element } from 'cheerio';

const html = '<div class="container"><p>Hello</p></div>';
const $: CheerioAPI = cheerio.load(html);

// Type-safe element selection
const elements: cheerio.Cheerio<Element> = $('.container p');
const text: string | undefined = elements.text();

Uso Avançado de Tipos

import type { AnyNode, CheerioOptions } from 'cheerio';

const options: CheerioOptions = {
  xmlMode: true,
  decodeEntities: false
};

const $ = cheerio.load('<xml><item>data</item></xml>', options);

Suporte a Ambientes

Requisitos do Node.js

Versão mínima do Node.js: 18.17 ou superior
Recomendado: Node.js 20+ para melhor performance
O Cheerio foi projetado exclusivamente para uso server-side

Limitações do Browser

⚠️ Importante: O Cheerio não foi projetado para ambientes de browser. É uma biblioteca server-side que:

Utiliza APIs específicas do Node.js
Não inclui tratamento de inconsistências do DOM que o jQuery fornece
É otimizada para parsing e manipulação de HTML server-side

Para ambientes de browser, use jQuery ou APIs DOM modernas.

Métodos de Carregamento Avançados

Carregando a partir de Buffers

import * as cheerio from 'cheerio';
import * as fs from 'fs';

// Load from buffer with encoding detection
const buffer = fs.readFileSync('index.html');
const $ = cheerio.loadBuffer(buffer);

Carregando a partir de URLs

import * as cheerio from 'cheerio';

// Fetch and parse HTML from a URL
const $ = await cheerio.fromURL('https://example.com');
console.log($('title').text());

Streaming de HTML

import * as cheerio from 'cheerio';
import * as fs from 'fs';

// Parse HTML streams
const writeStream = cheerio.stringStream({}, (err, $) => {
  if (err) {
    console.error('Parse error:', err);
    return;
  }
  
  console.log($('h1').text());
});

fs.createReadStream('document.html', { encoding: 'utf8' })
  .pipe(writeStream);

Opções de Configuração

Opções do Parser

import * as cheerio from 'cheerio';

const $ = cheerio.load(html, {
  // Use XML mode for XML documents
  xmlMode: false,
  
  // Decode HTML entities
  decodeEntities: true,
  
  // Set base URI for resolving relative URLs
  baseURI: 'https://example.com',
  
  // Enable/disable scripting
  scriptingEnabled: false
});

Problemas Comuns de Instalação

Conflitos de Versão do Node.js

Erro: Cannot find module 'cheerio' ou avisos de compatibilidade

Solução: Certifique-se de estar usando Node.js 18.17 ou superior:

node --version
# Should show v18.17.0 or higher

# Update Node.js if needed
npm install -g n  # For Unix systems
n latest

Problemas de Module ESM/CommonJS

Erro: require() of ES Module ou declarações import em CommonJS

Solução: Certifique-se de que seu package.json tenha o tipo de module correto:

{
  "type": "module"
}

Ou use a sintaxe de importação apropriada para seu ambiente.

Configuração TypeScript

Erro: Erros de compilação TypeScript com tipos do Cheerio

Solução: Atualize seu tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true
  }
}

Problemas de Memória com Documentos Grandes

Erro: JavaScript heap out of memory

Solução: Aumente o limite de memória do Node.js:

node --max-old-space-size=4096 your-script.js

Ou processe documentos em pedaços menores usando métodos de streaming.

Problemas de Encoding

Erro: Codificação de caracteres incorreta no HTML parseado

Solução: Use loadBuffer() com opções de encoding explícitas:

const $ = cheerio.loadBuffer(buffer, {
  encoding: {
    defaultEncoding: 'utf8'
  }
});

Verificação

Verifique se sua instalação funciona corretamente:

import * as cheerio from 'cheerio';

const $ = cheerio.load('<h1>Test</h1>');
console.log($('h1').text()); // Should output: "Test"

// Check version
console.log('Cheerio version:', cheerio.version || 'Version info not available');

Com estes passos de instalação, você está pronto para começar a fazer parsing e manipular HTML com a poderosa API similar ao jQuery do Cheerio em suas aplicações Node.js.

← Overview & Quick Start Core API Reference →