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
Step 2: Update Imports
import algoliasearch from 'algoliasearch';
const client = algoliasearch('APP_ID', 'API_KEY');
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('APP_ID', 'API_KEY');
import { liteClient } from 'algoliasearch/lite';
const searchClient = liteClient('APP_ID', 'SEARCH_KEY');
import { searchClient } from '@algolia/client-search';
Step 3: Remove initIndex and Update Method Calls
const index = client.initIndex('products');
const { hits } = await index.search('laptop');
await index.saveObjects(records);
await index.setSettings({ searchableAttributes: ['name'] });
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
const { taskID } = await index.saveObjects(records);
await index.waitTask(taskID);
const { taskID } = await client.saveObjects({ indexName: 'products', objects: records });
await client.waitForTask({ indexName: 'products', taskID });
Step 5: Update Error Handling
import { AlgoliaError } from 'algoliasearch';
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
grep -rn "initIndex\|\.search(\|\.saveObjects\|\.setSettings\|\.deleteObject\|\.waitTask" \
--include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" src/
npm test
npx tsc --noEmit
Rollback Procedure
npm install algoliasearch@4
git checkout -- src/
npm test
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.
