Installation

Cheerio est une implémentation côté serveur du cœur de jQuery conçue spécifiquement pour les environnements Node.js. Ce guide couvre toutes les façons d'installer et de configurer Cheerio dans vos projets.

Installation via gestionnaire de package

npm

npm install cheerio

yarn

yarn add cheerio

pnpm

pnpm add cheerio

bun

bun add cheerio

Syntaxe d'importation

ESM (ES Modules) - Recommandé

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

Importations déstructurées

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

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

Configuration TypeScript

Cheerio est livré avec des définitions TypeScript intégrées. Aucun package @types supplémentaire n'est requis.

Utilisation TypeScript de base

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

Utilisation avancée des types

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

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

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

Compatibilité des environnements

Exigences Node.js

Version Node.js minimale : 18.17 ou supérieure
Recommandé : Node.js 20+ pour de meilleures performances
Cheerio est conçu exclusivement pour un usage côté serveur

Limitations dans le navigateur

⚠️ Important : Cheerio n'est pas conçu pour les environnements de navigateur. C'est une bibliothèque côté serveur qui :

Utilise des API spécifiques à Node.js
N'inclut pas la gestion des incohérences DOM que fournit jQuery
Est optimisée pour l'analyse et la manipulation HTML côté serveur

Pour les environnements de navigateur, utilisez plutôt jQuery ou les API DOM modernes.

Méthodes de chargement avancées

Chargement depuis des 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);

Chargement depuis des URL

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

Options de configuration

Options de l'analyseur

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

Problèmes d'installation courants

Conflits de version Node.js

Erreur : Cannot find module 'cheerio' ou avertissements de compatibilité

Solution : Assurez-vous d'utiliser Node.js 18.17 ou supérieur :

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

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

Problèmes de module ESM/CommonJS

Erreur : require() of ES Module ou instructions import dans CommonJS

Solution : Assurez-vous que votre package.json a le bon type de module :

{
  "type": "module"
}

Ou utilisez la syntaxe d'importation appropriée pour votre environnement.

Configuration TypeScript

Erreur : Erreurs de compilation TypeScript avec les types Cheerio

Solution : Mettez à jour votre tsconfig.json :

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

Problèmes de mémoire avec des documents volumineux

Erreur : JavaScript heap out of memory

Solution : Augmentez la limite de mémoire de Node.js :

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

Ou traitez les documents en plus petits morceaux en utilisant les méthodes de streaming.

Problèmes d'encodage

Erreur : Encodage de caractères incorrect dans le HTML analysé

Solution : Utilisez loadBuffer() avec des options d'encodage explicites :

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

Vérification

Vérifiez que votre installation fonctionne correctement :

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

Avec ces étapes d'installation, vous êtes prêt à commencer à analyser et manipuler du HTML avec l'API puissante de Cheerio, similaire à jQuery, dans vos applications Node.js.

← Overview & Quick Start Core API Reference →