Skills Development Exa JS SDK Upgrade and Migration Guide

Exa JS SDK Upgrade and Migration Guide

v20260423
exa-upgrade-migration
This comprehensive guide provides a structured process for safely upgrading the `exa-js` SDK. It covers checking current vs. latest versions, handling potential breaking changes, and validating API compatibility (e.g., search, getContents, findSimilar). Follow these steps to ensure a smooth and reliable migration across different SDK versions.
Get Skill
405 downloads
Overview

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

  • [ ] Create branch: upgrade/exa-js-latest
  • [ ] Run npm install exa-js@latest
  • [ ] Run full test suite: npm test
  • [ ] Run upgrade verification script (checks all methods)
  • [ ] Check for deprecation warnings in output
  • [ ] Review changelog for breaking changes
  • [ ] Update any changed parameter names
  • [ ] Merge after all checks pass

Error Handling

IssueCauseSolution
Import error after upgradeAPI changeCheck import Exa from "exa-js" still works
Method not foundRenamed methodCheck SDK changelog
Type errorsParameter type changesUpdate TypeScript types
Tests failBreaking changeReview changelog, update code

Resources

Next Steps

For CI integration during upgrades, see exa-ci-integration.

Info
Category Development
Name exa-upgrade-migration
Version v20260423
Size 4.9KB
Updated At 2026-04-28
Language