home / skills / jeremylongshore / claude-code-plugins-plus-skills / firecrawl-upgrade-migration

firecrawl-upgrade-migration skill

safe

/plugins/saas-packs/firecrawl-pack/skills/firecrawl-upgrade-migration

This skill helps you upgrade and migrate FireCrawl SDKs by detecting breaking changes, planning steps, and validating with tests.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill firecrawl-upgrade-migration

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.8 KB

---
name: firecrawl-upgrade-migration
description: |
  Analyze, plan, and execute FireCrawl SDK upgrades with breaking change detection.
  Use when upgrading FireCrawl SDK versions, detecting deprecations,
  or migrating to new API versions.
  Trigger with phrases like "upgrade firecrawl", "firecrawl migration",
  "firecrawl breaking changes", "update firecrawl SDK", "analyze firecrawl version".
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(git:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# FireCrawl Upgrade & Migration

## Overview
Guide for upgrading FireCrawl SDK versions and handling breaking changes.

## Prerequisites
- Current FireCrawl SDK installed
- Git for version control
- Test suite available
- Staging environment

## Instructions

### Step 1: Check Current Version
```bash
npm list @firecrawl/sdk
npm view @firecrawl/sdk version
```

### Step 2: Review Changelog
```bash
open https://github.com/firecrawl/sdk/releases
```

### Step 3: Create Upgrade Branch
```bash
git checkout -b upgrade/firecrawl-sdk-vX.Y.Z
npm install @firecrawl/sdk@latest
npm test
```

### Step 4: Handle Breaking Changes
Update import statements, configuration, and method signatures as needed.

## Output
- Updated SDK version
- Fixed breaking changes
- Passing test suite
- Documented rollback procedure

## Error Handling
| SDK Version | API Version | Node.js | Breaking Changes |
|-------------|-------------|---------|------------------|
| 3.x | 2024-01 | 18+ | Major refactor |
| 2.x | 2023-06 | 16+ | Auth changes |
| 1.x | 2022-01 | 14+ | Initial release |

## Examples

### Import Changes
```typescript
// Before (v1.x)
import { Client } from '@firecrawl/sdk';

// After (v2.x)
import { FireCrawlClient } from '@firecrawl/sdk';
```

### Configuration Changes
```typescript
// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new FireCrawlClient({
  apiKey: 'xxx',
});
```

### Rollback Procedure
```bash
npm install @firecrawl/[email protected] --save-exact
```

### Deprecation Handling
```typescript
// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[FireCrawl]', warning.message);
      // Log to tracking system for proactive updates
    }
  });
}

// Common deprecation patterns to watch for:
// - Renamed methods: client.oldMethod() -> client.newMethod()
// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
// - Removed features: Check release notes before upgrading
```

## Resources
- [FireCrawl Changelog](https://github.com/firecrawl/sdk/releases)
- [FireCrawl Migration Guide](https://docs.firecrawl.com/migration)

## Next Steps
For CI integration during upgrades, see `firecrawl-ci-integration`.

Overview

This skill analyzes, plans, and executes FireCrawl SDK upgrades while detecting breaking changes and deprecations. It guides you through version discovery, changelog review, code adjustments, testing, and rollback preparation to keep your application stable during SDK transitions.

How this skill works

The skill inspects your current FireCrawl SDK version and scans change logs and release notes for breaking changes and deprecations. It generates an upgrade plan that lists code edits (imports, config keys, method signatures), runs or suggests test steps, and produces a rollback procedure. It flags Node.js or API compatibility issues and surfaces recommended fixes for common migration patterns.

When to use it

Before upgrading @firecrawl/sdk to any newer major or minor version
When you see deprecation warnings referencing FireCrawl in development logs
When CI tests fail after a dependency update and you suspect SDK changes
When preparing a release that depends on new FireCrawl API features
When auditing project compatibility with FireCrawl API versions or Node.js requirements

Best practices

Create a dedicated upgrade branch and commit incremental changes for traceability
Review the official changelog and migration guide before making code edits
Run the full test suite in a staging environment and check runtime warnings
Search and update imports, configuration keys, and renamed methods systematically
Document rollback steps and pin the working SDK version in package.json

Example use cases

Automate detection of renamed client classes and update import statements across the codebase
Generate a checklist of API parameter changes and the files affected for manual edits
Run a pre-upgrade compatibility check for Node.js and API version requirements
Create a CI job that installs the new SDK, runs tests, and fails the pipeline with a migration report
Produce a rollback script to reinstall a specific older @firecrawl/sdk version if issues appear in staging

FAQ

How do I find breaking changes for a specific FireCrawl version?

Check the FireCrawl changelog and release notes linked in the migration guide, then compare your current API usage to listed breaking changes and refactor imports/config as needed.

What if tests pass locally but fail in CI after upgrading?

Verify the CI Node.js runtime matches the SDK's required version, ensure environment variables like NODE_ENV are consistent, and re-run tests in a staging environment identical to CI.

How do I handle deprecations proactively?

Monitor development warnings for DeprecationWarning, log occurrences to your tracking system, and schedule code updates before the deprecated API is removed.