Node

O Firecrawl Node SDK é um SDK que encapsula a Firecrawl API para ajudar você a transformar sites em Markdown com facilidade.

​

Instalação

Para instalar o SDK do Firecrawl para Node, você pode usar o npm:

Node.js

# npm install @mendable/firecrawl-js

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

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

​

Uso

1. Obtenha uma chave de API em firecrawl.dev
2. Defina a chave de API como uma variável de ambiente chamada FIRECRAWL_API_KEY ou passe-a como parâmetro para a classe FirecrawlApp.

Veja um exemplo de como usar o SDK com tratamento de erros:

Node

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

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

// Fazer scraping de um site
const scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

// Fazer crawling de um site
const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
});

console.log(crawlResponse)

​

Extraindo dados de uma URL

Para extrair dados de uma única URL com tratamento de erros, use o método scrapeUrl. Ele recebe a URL como parâmetro e retorna os dados coletados como um dicionário.

Node

// Fazer scraping de um site:
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

​

Rastreamento de um site

Para rastrear um site com tratamento de erros, use o método crawlUrl. Ele recebe a URL inicial e parâmetros opcionais como argumentos. O parâmetro params permite especificar opções adicionais para a tarefa de rastreamento, como o número máximo de páginas a rastrear, domínios permitidos e o formato de saída. Veja Pagination para paginação automática/manual e limites.

Node

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

​

Rastreamento Somente do Sitemap

Use sitemap: "only" para rastrear apenas URLs do sitemap (a URL inicial sempre é incluída e a descoberta de links em HTML é ignorada).

Node

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

​

Iniciar um Crawl

Inicie um job sem esperar usando startCrawl. Ele retorna um ID de job que você pode usar para verificar o status. Use crawl quando quiser um “waiter” que bloqueia até a conclusão. Veja Paginação para comportamento e limites de paginação.

Node

const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);

​

Verificando o status do rastreamento

Para verificar o status de um trabalho de rastreamento com tratamento de erros, use o método checkCrawlStatus. Ele recebe o ID como parâmetro e retorna o status atual do trabalho de rastreamento.

Node

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

​

Cancelando um Crawl

Para cancelar um job de crawl, use o método cancelCrawl. Ele recebe o ID do job retornado por startCrawl como parâmetro e retorna o status do cancelamento.

Node.js

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

​

Mapeando um site

Para mapear um site com tratamento de erros, use o método mapUrl. Ele recebe a URL inicial como parâmetro e retorna os dados mapeados como um dicionário.

Node.js

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

​

Rastreando um site com WebSockets

Para rastrear um site com WebSockets, use o método crawlUrlAndWatch. Ele recebe a URL inicial e parâmetros opcionais como argumentos. O parâmetro params permite especificar opções adicionais para a tarefa de rastreamento, como o número máximo de páginas a rastrear, os domínios permitidos e o formato de saída.

Node

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

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

// Inicie um crawl e depois acompanhe
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);
});

// Comece a acompanhar (WS com fallback em HTTP)
await watcher.start();

​

Paginação

Os endpoints do Firecrawl para crawl e batch retornam uma URL next quando há mais dados disponíveis. O SDK de Node faz paginação automática por padrão e agrega todos os documentos; nesse caso, next será null. Você pode desativar a paginação automática ou definir limites.

​

Rastreamento

Use o método waiter crawl para a experiência mais simples, ou inicie um job e faça a paginação manualmente.

Rastreamento simples (paginação automática, padrão)

• Veja o fluxo padrão em Rastrear um site.

Rastreamento manual com controle de paginação (página única)

• Inicie um job e, em seguida, recupere uma página por vez com 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('rastreamento de página única:', crawlSingle.status, 'docs:', crawlSingle.data.length, 'próximo:', crawlSingle.next);

Rastreamento manual com limites (paginação automática + parada antecipada)

• Mantenha a paginação automática ativada, mas interrompa antecipadamente com maxPages, maxResults ou maxWaitTime.

Node

const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('crawl limitado:', crawlLimited.status, 'docs:', crawlLimited.data.length, 'próximo:', crawlLimited.next);

​

Coleta em lote

Use o método waiter batchScrape ou inicie uma tarefa e pagine manualmente.

Raspagem em lote simples (paginação automática, padrão)

• Veja o fluxo padrão em Raspagem em lote.

Coleta manual em lote com controle de paginação (página única)

• Inicie um job e, em seguida, recupere uma página por vez com 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('página única do lote:', batchSingle.status, 'docs:', batchSingle.data.length, 'próximo:', batchSingle.next);

Coleta manual em lote com limites (paginação automática + parada antecipada)

• Mantenha a paginação automática ligada, mas interrompa antes com maxPages, maxResults ou 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, 'próximo:', batchLimited.next);

​

Browser

Inicie sessões de navegador na nuvem e execute código remotamente.

​

Criar sessão

Node

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

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

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

​

Executar código

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"

Execute JavaScript em vez de 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",
});

Execute bash com o agent-browser:

Node

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

​

Perfis

Salve e reutilize o estado do navegador (cookies, localStorage, etc.) entre sessões:

Node

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

​

Conectar via CDP

Para controle completo do Playwright, conecte-se diretamente usando a URL do 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();

​

Listar e Encerrar Sessões

Node

// Listar sessões ativas
const { sessions } = await firecrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
  console.log(s.id, s.status, s.createdAt);
}

// Fechar uma sessão
await firecrawl.deleteBrowser(session.id);

​

Tratamento de erros

O SDK trata os erros retornados pela API do Firecrawl e lança as exceções apropriadas. Se ocorrer um erro durante uma solicitação, uma exceção será lançada com uma mensagem descritiva. Os exemplos acima mostram como lidar com esses erros usando blocos try/catch.