​
Instalación

Para instalar el SDK de Firecrawl para Node, puedes usar npm:
Node
# npm install @mendable/firecrawl-js

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

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

​
Uso

  1. Obtén una clave de API en firecrawl.dev
  2. Define la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala como parámetro a la clase FirecrawlApp.
Aquí tienes un ejemplo de cómo usar el SDK con manejo de errores:
Node
import Firecrawl from '@mendable/firecrawl-js';

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

// Extraer datos de un sitio web
const scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

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

console.log(crawlResponse)

​
Extracción de una URL

Para extraer una única URL con manejo de errores, usa el método scrapeUrl. Recibe la URL como parámetro y devuelve los datos extraídos como un diccionario.
Node
// Scrape a website:
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

​
Rastreo de un sitio web

Para rastrear un sitio web con manejo de errores, usa el método crawlUrl. Recibe la URL inicial y parámetros opcionales como argumentos. El argumento params te permite especificar opciones adicionales para la tarea de rastreo, como el número máximo de páginas a rastrear, los dominios permitidos y el formato de salida. Consulta Paginación para la paginación automática o manual y la configuración de límites.
Node
const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);

​
Iniciar un rastreo

Inicia un trabajo sin esperar usando startCrawl. Devuelve un ID de trabajo que puedes usar para comprobar el estado. Usa crawl cuando necesites un proceso bloqueante que espere hasta la finalización. Consulta Paginación para el comportamiento y los límites de paginación.
Node
const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);

​
Verificar el estado del rastreo

Para verificar el estado de un trabajo de rastreo con manejo de errores, usa el método checkCrawlStatus. Recibe el ID como parámetro y devuelve el estado actual del trabajo de rastreo.
Node.js
const estado = await firecrawl.getCrawlStatus("<id-de-rastreo>");
console.log(estado);

​
Cancelar un rastreo

Para cancelar un trabajo de rastreo, usa el método cancelCrawl. Recibe como parámetro el ID del trabajo iniciado con startCrawl y devuelve el estado de la cancelación.
Node
const ok = await firecrawl.cancelCrawl("<crawl-id>");
console.log("Cancelado:", ok);

​
Mapear un sitio web

Para mapear un sitio web con manejo de errores, utiliza el método mapUrl. Recibe la URL inicial como parámetro y devuelve los datos del mapeo como un diccionario.
Node
const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });
console.log(res.links);

​
Rastreo de un sitio web con WebSockets

Para rastrear un sitio web con WebSockets, usa el método crawlUrlAndWatch. Recibe la URL inicial y parámetros opcionales como argumentos. El argumento params te permite especificar opciones adicionales para la tarea de rastreo, como el número máximo de páginas a rastrear, los dominios permitidos y el formato de salida.
Node
import Firecrawl from '@mendable/firecrawl-js';

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

// Inicia un rastreo y luego míralo
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);
});

// Comienza a mirar (WS con alternativa HTTP)
await watcher.start();
Los puntos de conexión de Firecrawl para crawl y batch devuelven una URL next cuando hay más datos disponibles. El SDK de Node realiza la paginación automáticamente por defecto y agrega todos los documentos; en ese caso, next será null. Puedes desactivar la paginación automática o establecer límites.

​
Rastreo

Usa el método auxiliar crawl para la forma más sencilla, o inicia un job y pagina manualmente.
Rastreo simple (paginación automática, por defecto)
Rastreo manual con control de paginación (una sola página)
  • Inicia un trabajo y luego recupera una página a la vez con autoPaginate: false.
Nodo
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('rastreo de una sola página:', crawlSingle.status, 'docs:', crawlSingle.data.length, 'siguiente:', crawlSingle.next);
Rastreo manual con límites (paginación automática + parada anticipada)
  • Mantén la paginación automática activada, pero deténla antes con maxPages, maxResults o maxWaitTime.
Node
const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('rastreo limitado:', crawlLimited.status, 'docs:', crawlLimited.data.length, 'siguiente:', crawlLimited.next);

​
Scrape por lotes

Usa el método waiter batchScrape, o inicia un job y pagina manualmente.
Raspado por lotes simple (paginación automática, predeterminado)
Raspado manual por lotes con control de paginación (una sola página)
  • Inicia un job y luego recupera una página a la vez con 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('lote, una sola página:', batchSingle.status, 'docs:', batchSingle.data.length, 'siguiente:', batchSingle.next);
Extracción manual por lotes con límites (paginación automática + detención anticipada)
  • Mantén la paginación automática activada, pero deténla antes con maxPages, maxResults o maxWaitTime.
Node
const batchLimited = await firecrawl.getBatchScrapeStatus(batchJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 100,
  maxWaitTime: 20,
});
console.log('lote limitado:', batchLimited.status, 'docs:', batchLimited.data.length, 'siguiente:', batchLimited.next);

​
Manejo de errores

El SDK gestiona los errores devueltos por la API de Firecrawl y arroja las excepciones correspondientes. Si se produce un error durante una solicitud, se generará una excepción con un mensaje descriptivo. Los ejemplos anteriores muestran cómo manejar estos errores con bloques try/catch.