Exa Upgrade & Migration

Prerequisites

• Current/target versions, compatibility notes, sanitized evaluation set, acceptance thresholds, and a rollback owner.
• Separate staging credentials plus a policy/data review for any query/result migration or automation change.

Output

• A staged upgrade record with compatibility/evaluation evidence, owner, observation window, and rollback revision.
• A safe pause decision when retrieval quality, latency, policy, or data handling regresses.

Examples

Upgrade in staging, run unit tests and sanitized evaluation queries through prior and target configurations, compare aggregate relevance/latency/error metrics, then release an approved canary. Roll back on regression and do not bulk-replay customer queries or export private result data to validate the 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

Resources

• exa-js on npm
• exa-js GitHub
• Exa Changelog

Next Steps

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