Skip to main content Analyze, plan, and execute Exa SDK upgrades with breaking change detection.
Use when upgrading Exa SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade exa", "exa migration",
"exa breaking changes", "update exa SDK", "analyze exa version".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill exa-upgrade-migration ai automation claude-code devops mcp ai-agents
Exa Upgrade & Migration
Current State
!npm list exa-js 2>/dev/null | grep exa-js || echo 'exa-js not installed'
!npm view exa-js version 2>/dev/null || echo 'cannot check latest'
Overview
Guide for upgrading the exa-js SDK. The SDK import is import Exa from "exa-js" and the client is instantiated with new Exa(apiKey). This skill covers checking for updates, handling breaking changes, and validating after upgrade.
Instructions
Step 1: Check Current vs Latest Version
set -euo pipefail
echo "Current version:"
npm list exa-js 2>/dev/null || echo "Not installed"
echo ""
echo "Latest available:"
npm view exa-js version
echo ""
echo "Changelog:"
npm view exa-js repository.url
Step 2: Create Upgrade Branch
set -euo pipefail
git checkout -b upgrade/exa-js-latest
npm install exa-js@latest
npm test
Step 3: Verify API Compatibility import Exa from "exa-js";
async function verifyUpgrade() {
const exa = new Exa(process.env.EXA_API_KEY);
const checks = [];
// Check 1: Basic search
try {
const r = await exa.search("upgrade test", { numResults: 1 });
checks.push({ method: "search", status: "OK", results: r.results.length });
} catch (err: any) {
checks.push({ method: "search", status: "FAIL", error: err.message });
}
// Check 2: searchAndContents
try {
const r = await exa.searchAndContents("upgrade test", {
numResults: 1,
text: { maxCharacters: 100 },
highlights: { maxCharacters: 100 },
});
checks.push({
method: "searchAndContents",
status: "OK",
hasText: !!r.results[0]?.text,
hasHighlights: !!r.results[0]?.highlights,
});
} catch (err: any) {
checks.push({ method: "searchAndContents", status: "FAIL", error: err.message });
}
// Check 3: findSimilar
try {
const r = await exa.findSimilar("https://nodejs.org", { numResults: 1 });
checks.push({ method: "findSimilar", status: "OK", results: r.results.length });
} catch (err: any) {
checks.push({ method: "findSimilar", status: "FAIL", error: err.message });
}
// Check 4: getContents
try {
const r = await exa.getContents(["https://nodejs.org"], { text: true });
checks.push({ method: "getContents", status: "OK", hasContent: !!r.results[0]?.text });
} catch (err: any) {
checks.push({ method: "getContents", status: "FAIL", error: err.message });
}
console.table(checks);
const allPassed = checks.every(c => c.status === "OK");
console.log(`\nUpgrade verification: ${allPassed ? "PASSED" : "FAILED"}`);
return allPassed;
}
Step 4: Common Breaking Change Patterns // Import style (has been stable)
import Exa from "exa-js"; // default export
// Constructor (has been stable)
const exa = new Exa("api-key");
// If upgrading from a very old version, check:
// - Method names: searchAndContents (not searchWithContents)
// - findSimilarAndContents (not findSimilarWithContents)
// - Parameter names: numResults (not num_results)
// - Content options: text, highlights, summary as objects
// Check for deprecated parameters
// - livecrawl may be replaced by maxAgeHours in newer versions
// - Check changelog for parameter renames
Step 5: Rollback Procedure set -euo pipefail
# If tests fail, rollback
npm install exa-js@<previous-version> --save-exact
git checkout -- package-lock.json # restore lockfile
npm test # verify rollback works
Upgrade Checklist
Error Handling Issue Cause Solution Import error after upgrade API change Check import Exa from "exa-js" still works Method not found Renamed method Check SDK changelog Type errors Parameter type changes Update TypeScript types Tests fail Breaking change Review changelog, update code
Resources
Next Steps For CI integration during upgrades, see exa-ci-integration.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
