algolia-sdk-patterns

name	algolia-sdk-patterns
description	Apply production-ready algoliasearch v5 patterns: singleton client, typed search, error handling, and batch operations. Use when implementing Algolia integrations, refactoring SDK usage, or establishing team coding standards. Trigger: "algolia SDK patterns", "algolia best practices", "algolia code patterns", "idiomatic algolia".
allowed-tools	Read, Write, Edit
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","search","algolia"]
compatibility	Designed for Claude Code

Algolia SDK Patterns

Overview

Production-ready patterns for algoliasearch v5. Key architectural change from v4: all methods live on the client directly — no more client.initIndex(). Index name is passed as a parameter to every call.

Prerequisites

• algoliasearch v5+ installed
• Completed algolia-install-auth setup
• TypeScript project (patterns work in JS too, you just lose type safety)

Instructions

Examples

The client, result, error, batch, and tenant examples below establish a consistent v5 SDK boundary. Centralize credentials and index naming in that boundary so individual callers do not reimplement error or retry policy.

Pattern 1: Typed Singleton Client

// src/algolia/client.ts
import { algoliasearch, type Algoliasearch } from 'algoliasearch';

let _client: Algoliasearch | null = null;

export function getClient(): Algoliasearch {
  if (!_client) {
    const appId = process.env.ALGOLIA_APP_ID;
    const apiKey = process.env.ALGOLIA_ADMIN_KEY;
    if (!appId || !apiKey) {
      throw new Error(
        'ALGOLIA_APP_ID and ALGOLIA_ADMIN_KEY must be set. '
        + 'Get them from dashboard.algolia.com > Settings > API Keys'
      );
    }
    _client = algoliasearch(appId, apiKey);
  }
  return _client;
}

// For testing: reset singleton
  ():  {
  _client = ;
}