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 @mendable/firecrawl-js

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

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

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

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

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 '@mendable/firecrawl-js';

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 du JavaScript plutôt que du 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écuter 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 et 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 scrape

Utilisez un ID de tâche de scrape pour continuer à interagir avec le contexte de page restauré à partir de ce scrape :

interact(jobId, {...}) exécute du code dans la session de navigateur liée au scrape.
Le premier appel à interact initialise automatiquement la session à partir du contexte de scrape.
Les appels suivants à interact sur le même ID de tâche réutilisent cet état actif du navigateur.
stopInteraction(jobId) arrête la session interactive lorsque 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 déclenche des exceptions explicites pour toute erreur renvoyée par l’API Firecrawl. Encapsulez les appels dans des blocs try/catch, comme indiqué dans les exemples ci-dessus.

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

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 et fermer les sessions

Session interactive liée au scrape

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 et fermer les sessions

​Session interactive liée au scrape

​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 et fermer les sessions

Session interactive liée au scrape

Gestion des erreurs