firecrawl-upgrade-migration

name	firecrawl-upgrade-migration
description	Upgrade Firecrawl SDK versions and migrate between API versions (v0 to v1/v2). Use when upgrading the SDK, handling breaking changes between versions, or migrating from the old API to the current v2 API. Trigger with phrases like "upgrade firecrawl", "firecrawl migration", "firecrawl v2", "update firecrawl SDK", "firecrawl breaking changes".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(git:*)
version	1.11.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","firecrawl","api","migration"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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
# Check installed version
npm list @mendable/firecrawl-js

# Check latest available
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

// No change needed — import has been stable
import FirecrawlApp from "@mendable/firecrawl-js";

Crawl Method Changes (v0 -> v1)

// BEFORE (v0): crawlUrl with waitUntilDone
const result = await firecrawl.crawlUrl("https://example.com", {
  crawlerOptions: { limit: 50 },
  pageOptions: { onlyMainContent:  },
  : ,
});


 result =  firecrawl.(, {
  : ,
  : {
    : [],
    : ,
  },
});


 job =  firecrawl.(, {
  : ,
  : { : [] },
});
 status =  firecrawl.(job.);