Instalación

Cheerio es una implementación del lado del servidor del núcleo de jQuery diseñada específicamente para entornos Node.js. Esta guía cubre todas las formas de instalar y configurar Cheerio en tus proyectos.

Instalación con Gestor de Paquetes

npm

npm install cheerio

yarn

yarn add cheerio

pnpm

pnpm add cheerio

bun

bun add cheerio

Sintaxis de Importación

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!');

Importaciones Desestructuradas

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

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

Configuración de TypeScript

Cheerio incluye definiciones de TypeScript integradas. No se requiere ningún package @types adicional.

Uso Básico con 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 Avanzado de Tipos

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

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

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

Compatibilidad de Entornos

Requisitos de Node.js

Versión mínima de Node.js: 18.17 o superior
Recomendado: Node.js 20+ para el mejor rendimiento
Cheerio está diseñado exclusivamente para uso del lado del servidor

Limitaciones del Navegador

⚠️ Importante: Cheerio no está diseñado para entornos de navegador. Es una librería del lado del servidor que:

Usa APIs específicas de Node.js
No incluye el manejo de inconsistencias del DOM que proporciona jQuery
Está optimizada para el análisis y manipulación de HTML del lado del servidor

Para entornos de navegador, usa jQuery o las APIs modernas del DOM en su lugar.

Métodos de Carga Avanzados

Carga desde 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);

Carga desde URLs

import * as cheerio from 'cheerio';

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

HTML en Streaming

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);

Opciones de Configuración

Opciones del 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 Comunes de Instalación

Conflictos de Versión de Node.js

Error: Cannot find module 'cheerio' o advertencias de compatibilidad

Solución: Asegúrate de usar Node.js 18.17 o 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 Módulos ESM/CommonJS

Error: require() of ES Module o declaraciones import en CommonJS

Solución: Asegúrate de que tu package.json tenga el tipo de module correcto:

{
  "type": "module"
}

O usa la sintaxis de importación apropiada para tu entorno.

Configuración de TypeScript

Error: Errores de compilación de TypeScript con tipos de Cheerio

Solución: Actualiza tu tsconfig.json:

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

Problemas de Memoria con Documentos Grandes

Error: JavaScript heap out of memory

Solución: Aumenta el límite de memoria de Node.js:

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

O procesa documentos en fragmentos más pequeños usando métodos de streaming.

Problemas de Codificación

Error: Codificación de caracteres incorrecta en HTML parseado

Solución: Usa loadBuffer() con opciones de codificación explícitas:

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

Verificación

Verifica que tu instalación funcione correctamente:

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');

Con estos pasos de instalación, estás listo para comenzar a parsear y manipular HTML con la potente API similar a jQuery de Cheerio en tus aplicaciones Node.js.

← Overview & Quick Start Core API Reference →