OpenParable
Skip to content
← Back to skills

Algolia Upgrade Migration

Development
algolia-upgrade-migration

Algolia Upgrade Migration is an Agent Skill for development published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Upgrade algoliasearch from v4 to v5 with breaking change detection and codemod. Use when upgrading SDK versions, detecting deprecations, or migrating initIndex patterns. Trigger: "upgrade algolia", "algolia migration v5", "algolia breaking changes", "update algolia SDK", "algolia v4 to v5".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/algolia-pack/skills/algolia-upgrade-migration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/algolia-upgrade-migration, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Algolia Upgrade & Migration (v4 to v5)

Overview

Guide for upgrading algoliasearch from v4 to v5. The v5 release is a major rewrite: initIndex() is removed, all methods move to the client, and the import style changes.

Prerequisites

  • Current algoliasearch v4 installed
  • Git for version control (work in a branch)
  • Test suite passing on current version

Breaking Changes Summary

v4 Patternv5 Replacement
const client = algoliasearch(appId, key)import { algoliasearch } from 'algoliasearch'; const client = algoliasearch(appId, key);
const index = client.initIndex('name')Removed — pass indexName to every method
index.search('query')client.searchSingleIndex({ indexName, searchParams: { query } })
index.saveObjects(records)client.saveObjects({ indexName, objects })
index.saveObject(record)client.saveObject({ indexName, body: record })
index.partialUpdateObject(data)client.partialUpdateObject({ indexName, objectID, attributesToUpdate })
index.deleteObject('id')client.deleteObject({ indexName, objectID })
index.setSettings(settings)client.setSettings({ indexName, indexSettings })
index.getSettings()client.getSettings({ indexName })
index.browse()client.browse({ indexName, browseParams })
index.findObject(cb)client.findObject({ indexName, ... })
index.replaceAllObjects(records)client.replaceAllObjects({ indexName, objects })
index.saveSynonyms(syns)client.saveSynonyms({ indexName, synonymHit })
index.saveRule(rule)client.saveRule({ indexName, objectID, rule })
index.waitTask(taskID)client.waitForTask({ indexName, taskID })

Instructions

Step 1: Create Upgrade Branch and Install v5

git checkout -b upgrade/algoliasearch-v5
npm install algoliasearch@latest
npm list algoliasearch  # Verify v5.x.x

Step 2: Update Imports

// v4
import algoliasearch from 'algoliasearch';
const client = algoliasearch('APP_ID', 'API_KEY');

// v5
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('APP_ID', 'API_KEY');

// v5 lite client (search-only, frontend)
import { liteClient } from 'algoliasearch/lite';
const searchClient = liteClient('APP_ID', 'SEARCH_KEY');

// v5 individual API client (if you only need one)
import { searchClient } from '@algolia/client-search';

Step 3: Remove initIndex and Update Method Calls

// v4: index-based API
const index = client.initIndex('products');
const { hits } = await index.search('laptop');
await index.saveObjects(records);
await index.setSettings({ searchableAttributes: ['name'] });

// v5: client-based API with indexName parameter
const { hits } = await client.searchSingleIndex({
  indexName: 'products',
  searchParams: { query: 'laptop' },
});
await client.saveObjects({ indexName: 'products', objects: records });
await client.setSettings({
  indexName: 'products',
  indexSettings: { searchableAttributes: ['name'] },
});

Step 4: Update waitTask

// v4
const { taskID } = await index.saveObjects(records);
await index.waitTask(taskID);

// v5
const { taskID } = await client.saveObjects({ indexName: 'products', objects: records });
await client.waitForTask({ indexName: 'products', taskID });

Step 5: Update Error Handling

// v4: error classes from algoliasearch
import { AlgoliaError } from 'algoliasearch';

// v5: error classes
import { ApiError } from 'algoliasearch';

try {
  await client.searchSingleIndex({ indexName: 'products', searchParams: { query: 'test' } });
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`HTTP ${error.status}: ${error.message}`);
  }
}

Step 6: Find All Usage and Verify

# Find all files using Algolia v4 patterns
grep -rn "initIndex\|\.search(\|\.saveObjects\|\.setSettings\|\.deleteObject\|\.waitTask" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" src/

# Run tests
npm test

# Type-check
npx tsc --noEmit

Rollback Procedure

# If v5 breaks things, revert to v4
npm install algoliasearch@4
git checkout -- src/  # Restore v4 code
npm test              # Verify v4 still works

Error Handling

IssueCauseSolution
initIndex is not a functionv5 installed but v4 codeRemove initIndex, pass indexName to methods
searchSingleIndex is not a functionv4 installed but v5 codeRun npm install algoliasearch@latest
Type errors after upgradeChanged type signaturesUpdate to new parameter objects
default import errorv5 uses named exportsChange import algoliasearch to import { algoliasearch }

Resources

Next Steps

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