​
Installation

Pour installer le SDK Firecrawl pour Node, vous pouvez utiliser npm :
Node
# npm install @mendable/firecrawl-js

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: "fc-VOTRE-CLÉ-API" });

​
Utilisation

  1. Récupérez une clé d’API sur firecrawl.dev
  2. Définissez la clé d’API comme variable d’environnement nommée FIRECRAWL_API_KEY, ou transmettez-la en paramètre à la classe FirecrawlApp.
Voici un exemple d’utilisation du SDK avec gestion des erreurs :
Node
import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

// Récupérer le contenu d’un site web
const scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

// Explorer un site web
const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
});

console.log(crawlResponse)

​
Scraper une URL

Pour récupérer le contenu d’une URL avec gestion des erreurs, utilisez la méthode scrapeUrl. Elle prend l’URL en paramètre et renvoie les données récupérées sous forme de dictionnaire.
Node
// Scrape a website:
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

​
Explorer un site web

Pour explorer un site web avec gestion des erreurs, utilisez la méthode crawlUrl. Elle prend en arguments l’URL de départ et des paramètres optionnels. L’argument params vous permet de définir des options supplémentaires pour la tâche d’exploration, comme le nombre maximal de pages à explorer, les domaines autorisés et le format de sortie. Voir Pagination pour la pagination automatique/manuelle et la limitation.
Node.js
const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);

​
Démarrer un crawl

Lancez une tâche sans attendre avec startCrawl. Elle renvoie un ID de tâche que vous pouvez utiliser pour vérifier l’état. Utilisez crawl si vous voulez un « waiter » qui bloque jusqu’à la fin. Voir Pagination pour le comportement de pagination et les limites.
Node
const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);

​
Vérifier l’état du crawl

Pour consulter l’état d’un job de crawl avec gestion des erreurs, utilisez la méthode checkCrawlStatus. Elle prend l’ID en paramètre et renvoie l’état actuel du job de crawl.
Node
const status = await firecrawl.getCrawlStatus("<crawl-id>");
console.log(status);

​
Annuler un crawl

Pour annuler une tâche de crawl, utilisez la méthode cancelCrawl. Elle prend l’ID de la tâche lancée par startCrawl en paramètre et renvoie l’état de l’annulation.
Node
const ok = await firecrawl.cancelCrawl("<crawl-id>");
console.log("Annulé :", ok);

​
Cartographier un site web

Pour cartographier un site web avec gestion des erreurs, utilisez la méthode mapUrl. Elle prend l’URL de départ en paramètre et renvoie les données cartographiées sous forme de dictionnaire.
Node
const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });
console.log(res.links);

​
Explorer un site web avec WebSockets

Pour explorer un site web avec WebSockets, utilisez la méthode crawlUrlAndWatch. Elle prend en arguments l’URL de départ et des paramètres optionnels. L’argument params permet de définir des options supplémentaires pour le job d’exploration, comme le nombre maximal de pages à explorer, les domaines autorisés et le format de sortie.
Node
import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// Lancer un crawl puis le suivre
const { id } = await firecrawl.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

watcher.on('document', (doc) => {
  console.log('DOC', doc);
});

watcher.on('error', (err) => {
  console.error('ERR', err?.error || err);
});

watcher.on('done', (state) => {
  console.log('TERMINÉ', state.status);
});

// Démarrer l’observation (WS avec solution de repli HTTP)
await watcher.start();
Les points de terminaison Firecrawl pour crawl et batch renvoient une URL next lorsqu’il reste des données. Le SDK Node effectue, par défaut, une pagination automatique et agrège tous les documents ; dans ce cas, next vaut null. Vous pouvez désactiver la pagination automatique ou définir des limites.

​
Crawl

Utilisez la méthode d’attente crawl pour la solution la plus simple, ou démarrez un job et paginez manuellement.
Exploration simple (pagination automatique, par défaut)
Crawl manuel avec contrôle de la pagination (page unique)
  • Lancez un job, puis récupérez les pages une par une avec autoPaginate: false.
Node
const crawlStart = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 5 });
const crawlJobId = crawlStart.id;

const crawlSingle = await firecrawl.getCrawlStatus(crawlJobId, { autoPaginate: false });
console.log('exploration d’une seule page :', crawlSingle.status, 'docs :', crawlSingle.data.length, 'suivant :', crawlSingle.next);
Exploration manuelle avec limites (pagination automatique + arrêt anticipé)
  • Conservez la pagination automatique activée, mais arrêtez plus tôt avec maxPages, maxResults ou maxWaitTime.
Node
const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('exploration limitée :', crawlLimited.status, 'docs :', crawlLimited.data.length, 'suivant :', crawlLimited.next);

​
Scrape par lots

Utilisez la méthode du waiter batchScrape, ou lancez un job et paginez manuellement.
Collecte par lots simple (pagination automatique, par défaut)
Scraping par lots manuel avec contrôle de la pagination (page unique)
  • Lancez un job, puis récupérez les pages une par une avec autoPaginate: false.
Node
const batchStart = await firecrawl.startBatchScrape([
  'https://docs.firecrawl.dev',
  'https://firecrawl.dev',
], { options: { formats: ['markdown'] } });
const batchJobId = batchStart.id;

const batchSingle = await firecrawl.getBatchScrapeStatus(batchJobId, { autoPaginate: false });
console.log('lot page unique :', batchSingle.status, 'docs :', batchSingle.data.length, 'suivant :', batchSingle.next);
Scrape manuel par lots avec limites (pagination automatique + arrêt anticipé)
  • Laissez la pagination automatique activée, mais arrêtez plus tôt avec maxPages, maxResults ou maxWaitTime.
Node
const batchLimited = await firecrawl.getBatchScrapeStatus(batchJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 100,
  maxWaitTime: 20,
});
console.log('lot limité :', batchLimited.status, 'docs :', batchLimited.data.length, 'suivant :', batchLimited.next);

​
Gestion des erreurs

Le SDK gère les erreurs renvoyées par l’API Firecrawl et déclenche les exceptions appropriées. Si une erreur survient lors d’une requête, une exception est levée avec un message d’erreur explicite. Les exemples ci-dessus illustrent la gestion de ces erreurs au moyen de blocs try/catch.