or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

batch.mdcrawling.mdextraction.mdindex.mdmapping.mdmonitoring.mdscraping.mdsearch.mdusage.mdv1-api.md
tile.json

tessl/npm-mendable--firecrawl-js

JavaScript SDK for Firecrawl API that enables comprehensive web scraping, crawling, and data extraction with AI-ready output formats.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@mendable/firecrawl-js@4.3.x

To install, run

npx @tessl/cli install tessl/npm-mendable--firecrawl-js@4.3.0

index.mddocs/

Firecrawl JavaScript SDK

JavaScript/TypeScript SDK for the Firecrawl API that enables comprehensive web scraping, crawling, and data extraction with AI-ready output formats.

Package Information

  • Package Name: @mendable/firecrawl-js
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @mendable/firecrawl-js

Core Imports

// Unified client (recommended)
import Firecrawl from '@mendable/firecrawl-js';

// Direct v2 client
import { FirecrawlClient } from '@mendable/firecrawl-js';

// Legacy v1 client
import { FirecrawlAppV1 } from '@mendable/firecrawl-js';

Basic Usage

// Initialize the client
const app = new Firecrawl({ apiKey: 'your-api-key' });

// Scrape a single URL
const scrapeResult = await app.scrape('https://example.com', {
  formats: ['markdown', 'html']
});

// Crawl a website
const crawlResult = await app.crawl('https://example.com', {
  limit: 100,
  scrapeOptions: { formats: ['markdown'] }
});

Architecture

The SDK provides both current (v2) and legacy (v1) API access:

  • Unified Client (Firecrawl): Extends v2 client with .v1 property for backward compatibility
  • Direct v2 Client (FirecrawlClient): Current API with modern async patterns
  • Legacy v1 Client (FirecrawlAppV1): Feature-frozen v1 API for existing integrations

All clients support real-time job monitoring via WebSocket with automatic fallback to polling.

Core Types

// Client configuration
interface FirecrawlClientOptions {
  apiKey?: string | null;
  apiUrl?: string | null;
  timeoutMs?: number;
  maxRetries?: number;
  backoffFactor?: number;
}

// Document structure
interface Document {
  markdown?: string;
  html?: string;
  rawHtml?: string;
  json?: unknown;
  summary?: string;
  metadata?: DocumentMetadata;
  links?: string[];
  images?: string[];
  screenshot?: string;
  attributes?: Array<{
    selector: string;
    attribute: string;
    values: string[];
  }>;
  actions?: Record<string, unknown>;
  warning?: string;
  changeTracking?: Record<string, unknown>;
}

// Document metadata
interface DocumentMetadata {
  title?: string;
  description?: string;
  language?: string;
  keywords?: string | string[];
  robots?: string;
  ogTitle?: string;
  ogDescription?: string;
  ogUrl?: string;
  ogImage?: string;
  sourceURL?: string;
  statusCode?: number;
  error?: string;
  [key: string]: unknown;
}

Main Client Classes

// Unified client class
class Firecrawl extends FirecrawlClient {
  constructor(opts?: FirecrawlClientOptions);
  get v1(): FirecrawlAppV1;
}

// Direct v2 client
class FirecrawlClient {
  constructor(options?: FirecrawlClientOptions);
  
  // Core methods available - see capability sections below
  scrape(url: string, options?: ScrapeOptions): Promise<Document>;
  search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;
  map(url: string, options?: MapOptions): Promise<MapData>;
  crawl(url: string, req?: CrawlOptions): Promise<CrawlJob>;
  batchScrape(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeJob>;
  extract(args: any): Promise<ExtractResponse>;
  watcher(jobId: string, opts?: WatcherOptions): Watcher;
}

Capabilities

Web Scraping

Single URL scraping with multiple output formats including structured data extraction.

Key APIs:

scrape(url: string, options?: ScrapeOptions): Promise<Document>;

Web Scraping Documentation

Web Crawling

Recursive website crawling with configurable limits, path filtering, and webhook support.

Key APIs:

startCrawl(url: string, req?: CrawlOptions): Promise<CrawlResponse>;
getCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<CrawlJob>;
crawl(url: string, req?: CrawlOptions): Promise<CrawlJob>;

Web Crawling Documentation

Batch Operations

Concurrent processing of multiple URLs with job monitoring and error handling.

Key APIs:

startBatchScrape(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeResponse>;
getBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<BatchScrapeJob>;
batchScrape(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeJob>;

Batch Operations Documentation

Search

Web search with optional result scraping across different sources (web, news, images).

Key APIs:

search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;

Search Documentation

Site Mapping

Discover and map website URLs using sitemaps and crawling techniques.

Key APIs:

map(url: string, options?: MapOptions): Promise<MapData>;

Site Mapping Documentation

Data Extraction

LLM-powered structured data extraction using natural language prompts or schemas.

Key APIs:

startExtract(args: any): Promise<ExtractResponse>;
getExtractStatus(jobId: string): Promise<ExtractResponse>;
extract(args: any): Promise<ExtractResponse>;

Data Extraction Documentation

Real-time Monitoring

WebSocket-based job monitoring with automatic fallback to polling for long-running operations.

Key APIs:

watcher(jobId: string, opts?: WatcherOptions): Watcher;

Real-time Monitoring Documentation

Usage Analytics

Monitor API usage, credits, tokens, and queue status for billing and optimization.

Key APIs:

getConcurrency(): Promise<ConcurrencyCheck>;
getCreditUsage(): Promise<CreditUsage>;
getTokenUsage(): Promise<TokenUsage>;
getQueueStatus(): Promise<QueueStatusResponse>;

Usage Analytics Documentation

Legacy V1 API

Feature-frozen v1 API with additional capabilities like deep research and LLMs.txt generation.

Key APIs:

// Access via unified client
const v1Client = app.v1;

Legacy V1 API Documentation