> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Node
> Scrapez, crawlez et extrayez des données structurées depuis des sites web avec le SDK Node de 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 :
```js Node theme={null}
// 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
1. Récupérez une clé d’API sur [firecrawl.dev](https://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 `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](/fr/rate-limits#keyless-no-api-key)). Toutes les autres méthodes nécessitent une clé.
Voici un exemple d’utilisation du SDK avec gestion des erreurs :
```js Node theme={null}
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`.
```js Node.js theme={null}
// 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`.
```js Node theme={null}
const parsed = await firecrawl.parse(
{
data: "Node Parse
",
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](#pagination) pour la pagination automatique et manuelle.
```js Node.js theme={null}
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).
```js Node theme={null}
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](#pagination) pour le comportement de pagination et les limites.
```js Node theme={null}
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`.
```js Node theme={null}
const status = await firecrawl.getCrawlStatus("");
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`.
```js Node theme={null}
const ok = await firecrawl.cancelCrawl("");
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.
```js Node.js theme={null}
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.
```js Node theme={null}
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();
```
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.
* Voir le flux par défaut dans [Exploration d’un site web](#crawling-a-website).
* Lancez un job, puis récupérez les pages une par une avec `autoPaginate: false`.
```js Node theme={null}
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);
```
* Conservez la pagination automatique activée, mais arrêtez plus tôt avec `maxPages`, `maxResults` ou `maxWaitTime`.
```js Node theme={null}
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.
* Voir le flux par défaut dans [Batch Scrape](/fr/features/batch-scrape).
* Lancez un job, puis récupérez les pages une par une avec `autoPaginate: false`.
```js Node theme={null}
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);
```
* Laissez la pagination automatique activée, mais arrêtez plus tôt avec `maxPages`, `maxResults` ou `maxWaitTime`.
```js Node theme={null}
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
```js Node theme={null}
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
```js Node theme={null}
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 :
```js Node theme={null}
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 :
```js Node theme={null}
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 :
```js Node theme={null}
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 :
```js Node theme={null}
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
```js Node theme={null}
// 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é.
```js Node theme={null}
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](https://www.firecrawl.dev/agent-onboarding/SKILL.md) pour obtenir des instructions d’onboarding automatisé.