Node SDK | Firecrawl

Faça scraping de páginas individuais, rastreie sites inteiros e mapeie URLs no seu aplicativo Node.js. O SDK gerencia a paginação, as novas tentativas e a consulta assíncrona de jobs para que você possa se concentrar nos dados retornados.

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

Obtenha uma chave de API em firecrawl.dev
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: 600 });
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: 600,
  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);

Sessão interativa vinculada ao scraping

Use o ID do job de scraping para continuar interagindo com o contexto da página reproduzida a partir desse scraping:

interact(jobId, {...}) executa código na sessão do navegador vinculada ao scraping.
A primeira chamada de interact inicializa automaticamente a sessão com base no contexto do scraping.
Chamadas adicionais de interact no mesmo ID do job reutilizam esse estado ativo do navegador.
stopInteraction(jobId) encerra a sessão interativa quando você terminar.

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

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.

Você é um agente de IA que precisa de uma chave de API do Firecrawl? Veja firecrawl.dev/agent-onboarding/SKILL.md para instruções automatizadas de onboarding.

Geral

Oficial

Comunidade

Node

Instalação

Uso

Extraindo dados de uma URL

Rastreamento de um site

Rastreamento Somente do Sitemap

Iniciar um Crawl

Verificando o status do rastreamento

Cancelando um Crawl

Mapeando um site

Rastreando um site com WebSockets

Rastreamento

Coleta em lote

Browser

Criar sessão

Executar código

Perfis

Conectar via CDP

Listar e Encerrar Sessões

Sessão interativa vinculada ao scraping

Tratamento de erros

Geral

Oficial

Comunidade

Documentation Index

​Instalação

​Uso

​Extraindo dados de uma URL

​Rastreamento de um site

​Rastreamento Somente do Sitemap

​Iniciar um Crawl

​Verificando o status do rastreamento

​Cancelando um Crawl

​Mapeando um site

​Rastreando um site com WebSockets

​Paginação

​Rastreamento

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

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

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

​Coleta em lote

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

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

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

​Browser

​Criar sessão

​Executar código

​Perfis

​Conectar via CDP

​Listar e Encerrar Sessões

​Sessão interativa vinculada ao scraping

​Tratamento de erros

Instalação

Uso

Extraindo dados de uma URL

Rastreamento de um site

Rastreamento Somente do Sitemap

Iniciar um Crawl

Verificando o status do rastreamento

Cancelando um Crawl

Mapeando um site

Rastreando um site com WebSockets

Paginação

Rastreamento

Coleta em lote

Browser

Criar sessão

Executar código

Perfis

Conectar via CDP

Listar e Encerrar Sessões

Sessão interativa vinculada ao scraping

Tratamento de erros