SDK Node | Firecrawl

Scrapez des pages individuelles, lancez un crawl sur des sites entiers et cartographiez les URL depuis votre application Node.js. Le SDK gère la pagination, les nouvelles tentatives et l’interrogation asynchrone des tâches pour que vous puissiez vous concentrer sur l’exploitation des données retournées.

Installation

Installez le SDK avec npm :

Node

// npm install firecrawl

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({
  // Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  // apiKey: "fc-YOUR-API-KEY",
});

Utilisation

Récupérez une clé d’API sur firecrawl.dev
Définissez la clé d’API comme variable d’environnement nommée FIRECRAWL_API_KEY, ou transmettez-la en paramètre à la classe Firecrawl.

Pas de clé d’API ? Vous pouvez instancier Firecrawl sans clé et utiliser scrape, search et interact sur l’offre Free sans clé (avec une limite de débit par IP — voir Limites de débit). Toutes les autres méthodes nécessitent une clé.

Voici un exemple d’utilisation du SDK avec gestion des erreurs :

Node

import { Firecrawl } from 'firecrawl';

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

Récupérez les données structurées d’une page à partir d’une URL avec la méthode scrape.

Node.js

// Extraire le contenu d’un site :
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

Analyse des fichiers importés

Utilisez parse lorsque vous souhaitez importer un fichier local (html, pdf, docx, xlsx, etc.) au lieu d’effectuer du scraping à partir d’une URL. parse ne prend pas en charge changeTracking ni les options propres au navigateur comme screenshot, branding, actions, waitFor, location et mobile.

Node

const parsed = await firecrawl.parse(
  {
    data: "<html><body><h1>Node Parse</h1></body></html>",
    filename: "upload.html",
    contentType: "text/html",
  },
  {
    formats: ["markdown"],
  },
);

console.log(parsed.markdown);

Crawl d’un site web

Crawlez l’ensemble d’un site web à partir d’une seule URL avec la méthode crawl. Vous pouvez définir une limite de pages, restreindre le crawl à des domaines spécifiques et choisir les formats de sortie. Consultez Pagination pour la pagination automatique et manuelle.

Node.js

const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);

Crawl uniquement via le sitemap

Utilisez sitemap: "only" pour explorer uniquement les URL du sitemap (l’URL de départ est toujours incluse et la découverte de liens HTML est désactivée).

Node

const job = await firecrawl.crawl('https://docs.firecrawl.dev', {
  sitemap: 'only',
  limit: 25,
});
console.log(job.status, job.data.length);

Démarrer un crawl

Lancez un crawl sans attendre qu’il se termine avec startCrawl. La méthode renvoie un ID de tâche que vous pourrez interroger plus tard. Utilisez plutôt crawl lorsque vous voulez bloquer 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

Vérifiez si un crawl est toujours en cours, terminé ou a échoué avec la méthode checkCrawlStatus. Passez l’ID de tâche renvoyé par startCrawl.

Node

const status = await firecrawl.getCrawlStatus("<crawl-id>");
console.log(status);

Annuler un crawl

Annulez un crawl en cours avec la méthode cancelCrawl. Passez l’ID de tâche renvoyé par startCrawl.

Node

const ok = await firecrawl.cancelCrawl("<crawl-id>");
console.log("Annulé :", ok);

Cartographier un site web

Découvrez toutes les URL d’un site web avec la méthode map. Fournissez une URL de départ et obtenez en retour la liste des pages découvertes.

Node.js

const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });
console.log(res.links);

Crawler un site web avec WebSockets

Recevez les résultats du crawl en temps réel avec la méthode crawlUrlAndWatch. Vous recevez chaque page dès qu’elle est explorée, au lieu d’attendre la fin de la tâche complète.

Node

import { Firecrawl } from 'firecrawl';

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('DONE', state.status);
});

// Démarrer l'observation (WS avec solution de repli HTTP)
await watcher.start();

Pagination

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)

Voir le flux par défaut dans Exploration d’un site web.

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)

Voir le flux par défaut dans Batch Scrape.

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

Navigateur

Démarrez des sessions de navigateur dans le cloud et exécutez du code à distance.

Créer une session

Node

import { Firecrawl } from 'firecrawl';

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

const session = await firecrawl.browser({ ttl: 600 });
console.log(session.id);          // ID de session
console.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

Exécuter du code

Node

const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
});
console.log(result.result); // "Hacker News"

Exécutez JavaScript plutôt que Python :

Node

const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://example.com"); const t = await page.title(); console.log(t);',
  language: "node",
});

Exécutez Bash avec agent-browser :

Node

const result = await firecrawl.browserExecute(session.id, {
  code: "agent-browser open https://example.com && agent-browser snapshot",
  language: "bash",
});

Profils

Enregistrez et réutilisez l’état du navigateur (cookies, localStorage, etc.) d’une session à l’autre :

Node

const session = await firecrawl.browser({
  ttl: 600,
  profile: {
    name: "my-profile",
    saveChanges: true,
  },
});

Connexion via le CDP

Pour bénéficier d’un contrôle complet via Playwright, connectez-vous directement à l’aide de l’URL CDP :

Node

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();

Lister & fermer les sessions

Node

// Lister les sessions actives
const { sessions } = await firecrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
  console.log(s.id, s.status, s.createdAt);
}

// Fermer une session
await firecrawl.deleteBrowser(session.id);

Session interactive liée au scraping

Utilisez l’ID d’une tâche de scraping pour continuer à interagir avec le contexte de page rejoué de ce scraping :

interact(jobId, {...}) exécute du code dans la session de navigateur liée au scraping.
Le premier appel à interact initialise automatiquement la session à partir du contexte de scraping.
Les appels suivants à interact avec le même ID de tâche réutilisent cet état actif du navigateur.
stopInteraction(jobId) arrête la session interactive une fois que vous avez terminé.

Node

const doc = await firecrawl.scrape("https://example.com", {
  actions: [{ type: "click", selector: "a[href='/pricing']" }],
});

const scrapeJobId = doc.metadata?.scrapeId;
if (!scrapeJobId) throw new Error("Missing scrape job id");

const run = await firecrawl.interact(scrapeJobId, {
  code: "console.log(await page.url())",
  language: "node",
  timeout: 60,
});
console.log(run.stdout);

await firecrawl.stopInteraction(scrapeJobId);

Gestion des erreurs

Le SDK lève des exceptions explicites pour toute erreur renvoyée par l’API Firecrawl. Encadrez les appels dans des blocs try/catch, comme dans les exemples ci-dessus.

Êtes-vous un agent IA qui a besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir des instructions d’onboarding automatisé.

Global

Officiel

Node

Installation

Utilisation

Scraper une URL

Analyse des fichiers importés

Crawl d’un site web

Crawl uniquement via le sitemap

Démarrer un crawl

Vérifier l’état du crawl

Annuler un crawl

Cartographier un site web

Crawler un site web avec WebSockets

Crawl

Scrape par lots

Navigateur

Créer une session

Exécuter du code

Profils

Connexion via le CDP

Lister & fermer les sessions

Session interactive liée au scraping

Gestion des erreurs

​Installation

​Utilisation

​Scraper une URL

​Analyse des fichiers importés

​Crawl d’un site web

​Crawl uniquement via le sitemap

​Démarrer un crawl

​Vérifier l’état du crawl

​Annuler un crawl

​Cartographier un site web

​Crawler un site web avec WebSockets

​Pagination

​Crawl

Exploration simple (pagination automatique, par défaut)

Crawl manuel avec contrôle de la pagination (page unique)

Exploration manuelle avec limites (pagination automatique + arrêt anticipé)

​Scrape par lots

Collecte par lots simple (pagination automatique, par défaut)

Scraping par lots manuel avec contrôle de la pagination (page unique)

Scrape manuel par lots avec limites (pagination automatique + arrêt anticipé)

​Navigateur

​Créer une session

​Exécuter du code

​Profils

​Connexion via le CDP

​Lister & fermer les sessions

​Session interactive liée au scraping

​Gestion des erreurs

Installation

Utilisation

Scraper une URL

Analyse des fichiers importés

Crawl d’un site web

Crawl uniquement via le sitemap

Démarrer un crawl

Vérifier l’état du crawl

Annuler un crawl

Cartographier un site web

Crawler un site web avec WebSockets

Pagination

Crawl

Scrape par lots

Navigateur

Créer une session

Exécuter du code

Profils

Connexion via le CDP

Lister & fermer les sessions

Session interactive liée au scraping

Gestion des erreurs