Firecrawl Upgrade & Migration
Current State
!npm list @mendable/firecrawl-js 2>/dev/null | grep firecrawl || echo 'Not installed'
Overview
Guide for upgrading @mendable/firecrawl-js SDK versions and migrating from Firecrawl API v0/v1 to v2. Covers breaking changes in import paths, method signatures, response formats, and the new extract v2 schema format.
Version History
| SDK Version | API Version | Key Changes |
|---|
| 1.x | v1 | asyncCrawlUrl, checkCrawlStatus, mapUrl added |
| 0.x | v0 | Legacy crawlUrl with waitUntilDone param |
Instructions
Step 1: Check Current Version
set -euo pipefail
npm list @mendable/firecrawl-js
npm view @mendable/firecrawl-js version
Step 2: Create Upgrade Branch
set -euo pipefail
git checkout -b upgrade/firecrawl-sdk
npm install @mendable/firecrawl-js@latest
npm test
Step 3: Migration — v0 to v1/v2
Import Changes
import FirecrawlApp from "@mendable/firecrawl-js";
Crawl Method Changes (v0 -> v1)
const result = await firecrawl.crawlUrl("https://example.com", {
crawlerOptions: { limit: 50 },
pageOptions: { onlyMainContent: true },
waitUntilDone: true,
});
const result = await firecrawl.crawlUrl("https://example.com", {
limit: 50,
scrapeOptions: {
formats: ["markdown"],
onlyMainContent: true,
},
});
const job = await firecrawl.asyncCrawlUrl("https://example.com", {
limit: 500,
scrapeOptions: { formats: ["markdown"] },
});
const status = await firecrawl.checkCrawlStatus(job.id);
Scrape Options Changes (v0 -> v1)
await firecrawl.scrapeUrl("https://example.com", {
pageOptions: { onlyMainContent: true },
extractorOptions: { mode: "llm-extraction", schema: mySchema },
});
await firecrawl.scrapeUrl("https://example.com", {
formats: ["markdown", "extract"],
onlyMainContent: true,
extract: { schema: mySchema },
});
Extract v2 Format (v1 -> v2)
await firecrawl.scrapeUrl(url, {
formats: ["extract"],
extract: { schema: { type: "object", ... } },
});
New Methods in v1+
const map = await firecrawl.mapUrl("https://example.com");
console.log(map.links);
const batch = await firecrawl.batchScrapeUrls(
["https://a.com", "https://b.com"],
{ formats: ["markdown"] }
);
const job = await firecrawl.asyncBatchScrapeUrls(urls, { formats: ["markdown"] });
const status = await firecrawl.checkBatchScrapeStatus(job.id);
Step 4: Run Tests and Verify
set -euo pipefail
npm test
npx tsx -e "
import FirecrawlApp from '@mendable/firecrawl-js';
const fc = new FirecrawlApp({ apiKey: process.env.FIRECRAWL_API_KEY! });
const r = await fc.scrapeUrl('https://example.com', { formats: ['markdown'] });
console.log('Success:', r.success, 'Chars:', r.markdown?.length);
"
Step 5: Rollback if Needed
set -euo pipefail
npm install @mendable/firecrawl-js@1.x.x --save-exact
npm test
Breaking Changes Checklist
Error Handling
| Issue | Cause | Solution |
|---|
crawlerOptions is not valid | Using v0 params on v1+ | Flatten to top-level options |
waitUntilDone is not valid | Removed in v1 | Use asyncCrawlUrl + checkCrawlStatus |
pageOptions not recognized | Renamed in v1 | Use scrapeOptions inside crawl |
Missing mapUrl method | SDK too old | Upgrade to latest version |
Resources
Next Steps
For CI integration during upgrades, see firecrawl-ci-integration.
