algolia-upgrade-migration | algolia-pack

Stats

Actions

Tags

algolia-upgrade-migration | algolia-pack

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 Pattern	v5 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

Issue	Cause	Solution
`initIndex is not a function`	v5 installed but v4 code	Remove `initIndex`, pass `indexName` to methods
`searchSingleIndex is not a function`	v4 installed but v5 code	Run `npm install algoliasearch@latest`
Type errors after upgrade	Changed type signatures	Update to new parameter objects
`default import` error	v5 uses named exports	Change `import algoliasearch` to `import { algoliasearch }`

Resources

Next Steps

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