Installation

Open Claude Code and run this command:

/plugin install algolia-pack@claude-code-plugins-plus

Use --global to install for all projects, or --project for current project only.

What It Does

> 24 production-ready Claude Code skills for Algolia search — real algoliasearch v5 API code, not templates.

Skills (24) plugin-local skills

algolia-ci-integration View full skill →

Configure Algolia CI/CD: GitHub Actions for index validation, automated reindexing on deploy, and integration testing against real Algolia indices.

ReadWriteEditBash(gh:*)Bash(npm:*)

Algolia CI Integration

Overview

Set up CI/CD pipelines for Algolia: run integration tests against a test index, validate index settings before deploy, and trigger reindexing on release.

Prerequisites

GitHub repository with Actions enabled
Algolia App ID and Admin key (stored as GitHub secrets)
npm/pnpm project with algoliasearch v5

Instructions

Examples

The workflow definitions below show the complete test, validation, and release-triggered reindex paths. Adapt only the index names and secret names to your repository; keep the test index isolated from production.

Step 1: Store Algolia Secrets


gh secret set ALGOLIA_APP_ID --body "YourApplicationID"
gh secret set ALGOLIA_ADMIN_KEY --body "your_admin_api_key"
gh secret set ALGOLIA_SEARCH_KEY --body "your_search_only_key"

Step 2: GitHub Actions — Test & Validate


# .github/workflows/algolia-ci.yml
name: Algolia CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
      ALGOLIA_ADMIN_KEY: ${{ secrets.ALGOLIA_ADMIN_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - name: Unit tests (mocked Algolia)
        run: npm test
      - name: Integration tests (real Algolia)
        if: env.ALGOLIA_APP_ID != ''
        run: npm run test:integration
        env:
          # Use timestamped index to avoid cross-PR collision
          ALGOLIA_TEST_INDEX: ci_test_${{ github.run_id }}_products

  validate-settings:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    env:
      ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
      ALGOLIA_ADMIN_KEY: ${{ secrets.ALGOLIA_ADMIN_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - name: Validate index settings match config
        run: npx tsx scripts/validate-algolia-settings.ts

Step 3: Index Settings Validation Script


// scripts/validate-algolia-settings.ts
import { algoliasearch } from 'algoliasearch';
import expectedSettings from '../config/algolia-settings.json' assert { type: 'json' };

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

async function validateSettings() {
  const actual = await client.getSettings({ indexName: 'products' });
  const errors: string[] = [];

  // Check critical settings match
  const checks: [string, any, any][] = [
    ['searchableAttributes&#


                
                  
                  algolia-common-errors
                  View full skill →
                
                
                  Diagnose and fix the top Algolia API errors: 400, 403, 404, 429, ApiError, RetryError, and indexing failures.
                  
                      ReadGrepBash(curl:*)Bash(npm:*)
                    
                
                
                  Algolia Common Errors
Overview
Quick reference for the most common Algolia errors, their root causes, and fixes. All examples use algoliasearch v5 client error types.
Prerequisites

The Algolia application ID and the least-privileged API key needed for the failing operation.
curl, jq, and the relevant application runtime available where you run diagnostics.
A safe test index when reproducing write failures; do not investigate against production with an unrestricted Admin key.

Instructions
Match the exact response status and request ID to the reference below, run the diagnostic script only with scoped credentials, then apply the smallest listed corrective action before retrying.
Error Handling
1. Invalid Application-ID or API key (403)

ApiError: Invalid Application-ID or API key

Cause: App ID or API key is wrong, expired, or deleted.
Fix:

# Verify your env vars are set
echo "APP_ID: $ALGOLIA_APP_ID"
echo "KEY set: ${ALGOLIA_ADMIN_KEY:+yes}"

# Test with curl
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}" | head -c 200

Get fresh keys: dashboard.algolia.com > Settings > API Keys.

2. Method not allowed with this API key (403)

ApiError: Method not allowed with this API key

Cause: Using a Search-Only key for a write operation (saveObjects, setSettings, etc.).
Fix: Use the Admin API key for write operations. Search-Only keys only permit search ACL.

// Wrong: search-only key for indexing
const client = algoliasearch(appId, searchOnlyKey);
await client.saveObjects({ ... }); // 403

// Right: admin key for indexing
const client = algoliasearch(appId, adminKey);
await client.saveObjects({ ... }); // Works


3. Index does not exist (404)

ApiError: Index products_staging does not exist

Cause: Searching an index that hasn't been created yet. Algolia creates indices lazily on first saveObjects.
Fix: Index some data first, or check the index name for typos:

# List all indices in your app
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}" | jq '.items[].name'


4. Rate limit exceeded (429)

ApiError: Too Many Requests

Cause: API key'


                
                  
                  algolia-core-workflow-a
                  View full skill →
                
                
                  Implement Algolia search with filters, facets, highlighting, and pagination.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Algolia Core Workflow A — Search & Filtering
Overview
Primary Algolia workflow: full-text search with filters, faceted navigation, hit highlighting, and pagination. Uses searchSingleIndex (v5) with real Algolia search parameters.
Prerequisites

Completed algolia-install-auth and algolia-hello-world setup
Index populated with records (see algolia-hello-world)
Index settings configured with searchableAttributes and attributesForFaceting

Instructions
Step 1: Configure Index for Filtering

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

await client.setSettings({
  indexName: 'products',
  indexSettings: {
    // What to search (ordered = priority matters)
    searchableAttributes: ['name', 'description', 'brand', 'category'],

    // What to filter/facet on — prefix with filterOnly() if no facet counts needed
    attributesForFaceting: [
      'searchable(brand)',           // Searchable facet: users can search within brand values
      'category',                     // Regular facet: shown in facet panels
      'filterOnly(price)',           // Filter only: no counts computed, saves CPU
      'filterOnly(in_stock)',
    ],

    // Custom ranking: tie-breaker after Algolia's relevance ranking
    customRanking: ['desc(sales_count)', 'desc(rating)'],

    // What comes back in hits
    attributesToRetrieve: ['name', 'brand', 'price', 'image_url', 'category'],
    attributesToHighlight: ['name', 'description'],
    attributesToSnippet: ['description:30'],  // 30-word snippet
  },
});

Step 2: Search with Filters

// Algolia filter syntax uses SQL-like expressions
const { hits, nbHits, facets } = await client.searchSingleIndex({
  indexName: 'products',
  searchParams: {
    query: 'running shoes',

    // Numeric/boolean/string filters
    filters: 'price < 150 AND in_stock = true',

    // OR: facetFilters for UI-driven filtering (array = OR, nested = AND)
    // facetFilters: [['category:shoes', 'category:sneakers'], ['brand:Nike']],
    //   ^ shoes OR sneakers, AND brand is Nike

    // Numeric range filters
    numericFilters: ['price >= 50', 'price <= 150'],

    // Request facet counts for these attributes
    facets: ['category', 'brand'],

    // Pagination
    hitsPerPage: 20,
    page: 0,

    // Highlighting
    highlightPreTag: '<mark>',
    highlightPostTag: '</mark>',
  },
});

console.log(`${nbHits} results found


                
                  
                  algolia-core-workflow-b
                  View full skill →
                
                
                  Implement Algolia indexing pipeline: data sync, partial updates, synonyms, and rules.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Algolia Core Workflow B — Indexing & Data Sync
Overview
Keep your Algolia index synchronized with your source database. Covers full reindex, incremental updates, partial updates, synonyms, and query rules.
Prerequisites

Completed algolia-install-auth setup
Familiarity with algolia-core-workflow-a (search)
Source database or API with change tracking (timestamps, events)

Instructions
Step 1: Full Reindex with replaceAllObjects

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// replaceAllObjects atomically swaps index content
// Internally: creates temp index → indexes all records → moves temp to target
// Search continues on old data until swap is complete — zero downtime
async function fullReindex(records: Record<string, any>[]) {
  const { taskID } = await client.replaceAllObjects({
    indexName: 'products',
    objects: records,
    batchSize: 1000,  // Records per batch (default 1000)
  });
  await client.waitForTask({ indexName: 'products', taskID });
  console.log(`Full reindex complete: ${records.length} records`);
}

Step 2: Incremental Updates with partialUpdateObject

// Only update changed fields — much faster than full saveObjects
async function updateProductPrice(objectID: string, newPrice: number) {
  await client.partialUpdateObject({
    indexName: 'products',
    objectID,
    attributesToUpdate: {
      price: newPrice,
      updated_at: new Date().toISOString(),
    },
    createIfNotExists: false,  // Don't create if missing
  });
}

// Batch partial updates
async function syncPriceChanges(changes: { id: string; price: number }[]) {
  const { taskID } = await client.partialUpdateObjects({
    indexName: 'products',
    objects: changes.map(c => ({
      objectID: c.id,
      price: c.price,
      updated_at: new Date().toISOString(),
    })),
    createIfNotExists: false,
  });
  await client.waitForTask({ indexName: 'products', taskID });
}

Step 3: Manage Synonyms

// Synonyms help users find products with different terminology
await client.saveSynonyms({
  indexName: 'products',
  synonymHit: [
    // Two-way synonym: any of these terms match each other
    {
      objectID: 'syn-1',
      type: 'synonym',
      synonyms: ['laptop', 'notebook', 'portable computer'],
    },
    // One-way synonym: "phone" also searches for "smartphone" but not reverse
    {
      objectID: 'syn-2',
      type: 'oneWaySynonym',
      input: 'phone',
      synonyms: ['smartphone', 'mobile phone', 'cell phone'],
    },


                
                  
                  algolia-cost-tuning
                  View full skill →
                
                
                  Optimize Algolia costs: understand search request vs record pricing, reduce operations with batching and caching, monitor usage via Analytics API.
                  
                      ReadGrep
                    
                
                
                  Algolia Cost Tuning
Overview
Algolia pricing is based on search requests and records. A search request is one API call (which may contain multiple queries via search({ requests: [...] })). Records are counted across all indices including replicas.
Prerequisites

Access to current Algolia usage, billing, and index statistics for the application being reviewed.
An Admin or monitoring credential used only from a trusted backend environment.
A reporting window that distinguishes production traffic from load tests and bots.

Pricing Structure (2025)

Plan
Records Included
Search Requests
Additional Cost


Build (Free)
1M records
10K requests/mo
N/A


Grow
100K free, then $0.40/1K
10K free, then $0.50/1K
Pay as you go


Grow Plus
100K free, then $0.40/1K
10K free, then $1.75/1K
+ AI features


Premium
Custom
Custom
Volume discounts


What Counts as Records

Every object in every index = 1 record
Standard replicas duplicate records (multiply your count)
Virtual replicas share records (no extra cost)
Synonyms and rules do NOT count as records

What Counts as Search Requests

searchSingleIndex() = 1 request
search({ requests: [q1, q2, q3] }) = 1 request (multi-query)
browse() = 1 request per page
saveObjects() = NOT a search request (indexing operations are free)

Instructions
Examples
The audit and analytics calls below show how to measure records, requests, and no-result searches before changing replicas, caching, or query design. Measure a baseline first so savings claims are testable.
Step 1: Audit Current Usage

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Check total records across all indices
const { items } = await client.listIndices();
let totalRecords = 0;
let replicaRecords = 0;

items.forEach(idx => {
  const records = idx.entries || 0;
  console.log(`${idx.name}: ${records.toLocaleString()} records, ${(idx.dataSize || 0 / 1024).toFixed(0)}KB`);
  if (idx.name.includes('_replica') || idx.primary) {
    replicaRecords += records;
  }
  totalRecords += records;
});

console.log(`\nTotal: ${totalRecords.toLocaleString()} records (${replicaRecords.toLocaleString()} in replicas)`);

Step 2: Replace Standard Replicas with Virtual Replicas

// Standard replicas: duplic


                
                  
                  algolia-data-handling
                  View full skill →
                
                
                  Implement Algolia data handling: record transforms, PII filtering before indexing, data retention, GDPR/CCPA compliance with Algolia's deleteByQuery and Insights deletion.
                  
                      ReadWriteEdit
                    
                
                
                  Algolia Data Handling
Overview
Algolia stores your records in their cloud. You control what data goes in (via saveObjects), what comes back (via attributesToRetrieve), and what users can search (via searchableAttributes). For privacy compliance, you must filter PII before indexing and implement deletion workflows.
Prerequisites

A documented data classification for the source records and approval to index only the searchable fields.
An Algolia Admin key held by the backend indexing job, never the browser.
A deletion and retention owner for data-subject requests before production records are copied to Algolia.

Data Flow: Source → Algolia → User

Source Database        Transform           Algolia Index           Search Response
┌──────────┐     ┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│ Full user │     │ Strip PII    │     │ Searchable       │     │ Retrieved    │
│ record    │ ──▶ │ Truncate     │ ──▶ │ fields only      │ ──▶ │ fields only  │
│ (all cols)│     │ Normalize    │     │ + ranking data   │     │ (UI needs)   │
└──────────┘     └──────────────┘     └──────────────────┘     └──────────────┘

Instructions
Examples
The transformations below demonstrate an allowlist-first record shape, explicit PII removal, deletion handling, and bounded retention. Apply the same policy to every source connector rather than relying on dashboard settings alone.
Step 1: Transform Records Before Indexing

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Define what goes into Algolia — NOT everything from your DB
interface AlgoliaProduct {
  objectID: string;
  name: string;
  description: string;     // Truncated, plain text
  category: string;
  brand: string;
  price: number;
  in_stock: boolean;
  image_url: string;
  rating: number;
  _tags: string[];
}

function transformForAlgolia(dbRecord: any): AlgoliaProduct {
  return {
    objectID: dbRecord.id,
    name: dbRecord.name,
    description: stripHtml(dbRecord.description).substring(0, 5000),
    category: dbRecord.category?.name || 'uncategorized',
    brand: dbRecord.brand?.name || '',
    price: dbRecord.price_cents / 100,
    in_stock: dbRecord.inventory_count > 0,
    image_url: dbRecord.images?.[0]?.url || '',
    rating: dbRecord.avg_rating || 0,
    _tags: buildTags(dbRecord),
  };
}

// Strip HTML tags for clean search text
function stripHtml(html: string): string {
  return html?.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim() || '';
}

function buildTags(record: any): string[] {
  const tags: string[] = [];
  if (record.is_featured) tags.push('featured');
  if (record.is_new) tags.push('ne


                
                  
                  algolia-debug-bundle
                  View full skill →
                
                
                  Collect Algolia debug evidence: index stats, API key ACLs, query logs, and network diagnostics for support tickets.
                  
                      ReadBash(curl:*)Bash(npm:*)Bash(tar:*)Bash(jq:*)Grep
                    
                
                
                  Algolia Debug Bundle
Overview
Collect all necessary diagnostic information for Algolia support tickets or internal troubleshooting. Uses real Algolia API endpoints to gather index stats, key permissions, and query performance data.
Prerequisites

ALGOLIA_APP_ID and ALGOLIA_ADMIN_KEY environment variables set
curl and jq available
Permission to read API key ACLs and index settings

Instructions
Examples
The bundle script below is the support-ready example. It gathers configuration and response metadata into a timestamped directory while redacting secret values from the collected files.
Step 1: Create the Debug Bundle Script

#!/bin/bash
# algolia-debug-bundle.sh
set -euo pipefail

APP_ID="${ALGOLIA_APP_ID:?Set ALGOLIA_APP_ID}"
API_KEY="${ALGOLIA_ADMIN_KEY:?Set ALGOLIA_ADMIN_KEY}"
BUNDLE_DIR="algolia-debug-$(date +%Y%m%d-%H%M%S)"
BASE_URL="https://${APP_ID}-dsn.algolia.net"
HEADERS=(-H "X-Algolia-Application-Id: ${APP_ID}" -H "X-Algolia-API-Key: ${API_KEY}")

mkdir -p "$BUNDLE_DIR"

echo "=== Algolia Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" | tee -a "$BUNDLE_DIR/summary.txt"
echo "App ID: $APP_ID" | tee -a "$BUNDLE_DIR/summary.txt"

# 1. List all indices with record counts
echo "--- Indices ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/indexes" "${HEADERS[@]}" \
  | jq '.items[] | {name, entries, dataSize, lastBuildTimeS}' \
  > "$BUNDLE_DIR/indices.json" 2>/dev/null
echo "Indices saved" >> "$BUNDLE_DIR/summary.txt"

# 2. Check API key permissions (redacted key)
echo "--- API Key ACL ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/keys" "${HEADERS[@]}" \
  | jq '.keys[] | {description, acl, indexes, maxQueriesPerIPPerHour, validity}' \
  > "$BUNDLE_DIR/api-keys-acl.json" 2>/dev/null
echo "Key ACLs saved (keys redacted)" >> "$BUNDLE_DIR/summary.txt"

# 3. Get recent query logs (last 1000)
echo "--- Query Logs ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "${BASE_URL}/1/logs?length=100&type=all" "${HEADERS[@]}" \
  | jq '.logs[] | {timestamp, method, url, answer_code, processing_time_ms, query_nb_hits}' \
  > "$BUNDLE_DIR/query-logs.json" 2>/dev/null
echo "Last 100 log entries saved" >> "$BUNDLE_DIR/summary.txt"

# 4. Network connectivity test
echo "--- Network Diagnostics ---" >> "$BUNDLE_DIR/summary.txt"
for host in "${APP_ID}-dsn.algolia.net" &q


                
                  
                  algolia-deploy-integration
                  View full skill →
                
                
                  Deploy Algolia-powered apps to Vercel, Fly.
                  
                      ReadWriteEditBash(vercel:*)Bash(fly:*)Bash(gcloud:*)Bash(npm:*)
                    
                
                
                  Algolia Deploy Integration
Overview
Deploy Algolia-powered applications to production platforms with proper API key separation (Admin on backend, Search-Only on frontend) and InstantSearch widget integration.
Prerequisites

Algolia App ID + Admin key (backend) + Search-Only key (frontend)
Platform CLI installed (vercel, fly, or gcloud)
algoliasearch v5 for backend, react-instantsearch or instantsearch.js for frontend

Instructions
Examples
The deployment patterns below keep the Admin key server-side and give the frontend only a search-safe credential. Exercise the health endpoint after rollout before directing user traffic to the new search surface.
Step 1: Backend API Key Configuration
Vercel

# Environment variables in Vercel
vercel env add ALGOLIA_APP_ID production       # Your Application ID
vercel env add ALGOLIA_ADMIN_KEY production     # Admin key (server-side only)
vercel env add ALGOLIA_SEARCH_KEY production    # Search-only key (can be public)

# For client-side access (Next.js convention)
vercel env add NEXT_PUBLIC_ALGOLIA_APP_ID production
vercel env add NEXT_PUBLIC_ALGOLIA_SEARCH_KEY production

Fly.io

fly secrets set \
  ALGOLIA_APP_ID=YourApplicationID \
  ALGOLIA_ADMIN_KEY=your_admin_key \
  ALGOLIA_SEARCH_KEY=your_search_key

Google Cloud Run

# Store in Secret Manager
echo -n "your_admin_key" | gcloud secrets create algolia-admin-key --data-file=-
echo -n "your_search_key" | gcloud secrets create algolia-search-key --data-file=-

# Deploy with secrets mounted as env vars
gcloud run deploy search-service \
  --image gcr.io/$PROJECT_ID/search-service \
  --set-secrets=ALGOLIA_ADMIN_KEY=algolia-admin-key:latest,ALGOLIA_SEARCH_KEY=algolia-search-key:latest \
  --region us-central1

Step 2: Backend Search API (Next.js API Route)

// app/api/search/route.ts
import { algoliasearch } from 'algoliasearch';
import { NextRequest, NextResponse } from 'next/server';

const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

export async function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get('q') || '';
  const page = parseInt(request.nextUrl.searchParams.get('page') || '0');

  const { hits, nbHits, nbPages } = await client.searchSingleIndex({
    indexName: 'products',
    searchParams: {
      query,
      hitsPerPage: 20,
      page,
      attributesToRetrieve: ['name', 'price', 'image_url', 'category'],
      attributesToHighlight: ['name'],
    },
  });

  return NextResponse.json({ hits, totalHits: nbHits, totalPages: nbP


                
                  
                  algolia-enterprise-rbac
                  View full skill →
                
                
                  Configure Algolia enterprise access control: team-scoped API keys, Secured API Keys for multi-tenant RBAC, dashboard team management, and audit logging.
                  
                      ReadWriteEdit
                    
                
                
                  Algolia Enterprise RBAC
Overview
Algolia's access control is built on API keys with ACL (Access Control Lists). Each key has specific permissions, index restrictions, and rate limits. For multi-tenant apps, Secured API Keys provide per-user filtering without creating individual keys. For team management, Algolia's dashboard supports team members with role-based access.
Prerequisites

An Algolia organization or application administrator authorized to inspect and change API-key ACLs.
A current inventory of services, users, and indices that require access.
A safe rotation path for any key whose ACL or validity will change.

API Key ACL Permissions

ACL
Operations Allowed
Use For


search
Search queries
Frontend, search-only clients


browse
Browse/export all records
Data export, migration scripts


addObject
Add or replace records
Indexing pipelines


deleteObject
Delete records
Data cleanup, GDPR deletion


editSettings
Modify index settings
Deployment scripts


listIndexes
List all indices
Monitoring, health checks


deleteIndex
Delete entire indices
Admin operations only


analytics
Read analytics data
Dashboards, reporting


recommendation
Algolia Recommend API
Product recommendations


usage
Read usage data
Billing monitoring


logs
Read API logs
Debugging, audit


Instructions
Examples
The API-key and role examples below show least-privilege grants for common service and tenant boundaries. Start with the narrowest index and ACL set, then verify it against the caller's actual operation.
Step 1: Define Application Roles

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Role definitions with minimal permissions
const ROLES = {
  // Backend search service: search only, scoped to specific indices
  searchService: {
    acl: ['search'] as const,
    description: 'Search service — production read-only',
    indexes: ['products', 'articles'],
    maxQueriesPerIPPerHour: 100000,
  },

  // Indexing pipeline: write records, no search or delete
  indexingPipeline: {
    acl: ['addObject', 'editSettings', '


                
                  
                  algolia-hello-world
                  View full skill →
                
                
                  Create a minimal working Algolia example — index records and search them.
                  
                      ReadWriteEditBash(npm:*)Bash(node:*)Bash(npx:*)
                    
                
                
                  Algolia Hello World
Overview
Index records into Algolia and search them back — the two fundamental operations. Uses the algoliasearch v5 client where all methods live on the client directly (no initIndex).
Prerequisites

algoliasearch v5 installed (npm install algoliasearch)
ALGOLIA_APP_ID and ALGOLIA_ADMIN_KEY environment variables set
See algolia-install-auth for setup

Instructions
Step 1: Index Records with saveObjects

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

// saveObjects adds or replaces records. Each must have objectID
// (or Algolia auto-generates one).
const { taskID } = await client.saveObjects({
  indexName: 'movies',
  objects: [
    { objectID: '1', title: 'The Matrix', year: 1999, genre: 'sci-fi' },
    { objectID: '2', title: 'Inception', year: 2010, genre: 'sci-fi' },
    { objectID: '3', title: 'Pulp Fiction', year: 1994, genre: 'crime' },
  ],
});

// Wait for indexing to complete before searching
await client.waitForTask({ indexName: 'movies', taskID });
console.log('Indexing complete.');

Step 2: Search with searchSingleIndex

// Basic search — Algolia searches all searchableAttributes by default
const { hits } = await client.searchSingleIndex({
  indexName: 'movies',
  searchParams: { query: 'matrix' },
});

console.log(`Found ${hits.length} results:`);
hits.forEach(hit => {
  // _highlightResult shows which parts matched
  console.log(`  ${hit.title} (${hit.year})`);
});

Step 3: Configure Index Settings

// Settings define how Algolia ranks results
await client.setSettings({
  indexName: 'movies',
  indexSettings: {
    searchableAttributes: ['title', 'genre'],       // Fields to search
    attributesForFaceting: ['genre', 'year'],        // Filterable fields
    customRanking: ['desc(year)'],                   // Tie-breaker: newer first
    attributesToRetrieve: ['title', 'year', 'genre'],// Fields returned in hits
  },
});

Output

Indexing complete.
Found 1 results:
  The Matrix (1999)

Error Handling

Error
Cause
Solution


Invalid Application-ID or API key
Wrong credentials
Verify in dashboard > Settings > API Keys


Record is too big
Object > 10KB (free) or 100KB (paid)
Reduce record size 
                
              
                
                  
                  algolia-incident-runbook
                  View full skill →
                
                
                  Execute Algolia incident response: triage search failures, distinguish Algolia-side vs your-side issues, apply fallbacks, and run postmortems.
                  
                      ReadGrepBash(curl:*)Bash(npm:*)
                    
                
                
                  Algolia Incident Runbook
Overview
Rapid incident response procedures for Algolia search failures. Algolia's infrastructure is distributed across multiple data centers with automatic failover, so true Algolia outages are rare. Most incidents are caused by API key issues, settings drift, or indexing pipeline failures on your side.
Prerequisites

Current incident owner, communications channel, and an approved escalation path.
Read-only access to Algolia status, application metrics, and a representative search request.
A defined production index and a safe way to distinguish it from staging before taking remediation action.

Instructions
Use the severity classification and triage sequence below to establish impact before changing settings or reindexing. Record timestamps, request IDs, and the decision owner as the incident progresses.
Examples
The decision tree, remediation table, and communication templates are executable incident examples: choose the branch matching observed impact and send only the update appropriate to the confirmed severity.
Severity Classification

Level
Definition
Response
Examples


P1
Search completely down
< 15 min
403/500 on all queries, Algolia unreachable


P2
Degraded search
< 1 hour
High latency, partial results, stale data


P3
Minor issue
< 4 hours
Analytics not updating, synonyms wrong


P4
No user impact
Next day
Monitoring gap, test failures


Quick Triage (Run These First)

#!/bin/bash
echo "=== ALGOLIA TRIAGE ==="

# 1. Is Algolia's infrastructure up?
echo -n "Algolia Status: "
curl -s https://status.algolia.com/api/v2/status.json | jq -r '.status.description'

# 2. Can we reach our Algolia app?
echo -n "API Connectivity: "
curl -s -o /dev/null -w "HTTP %{http_code} (%{time_total}s)" \
  "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}"
echo ""

# 3. Can we actually search?
echo -n "Search test: "
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes/products/query" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_SEARCH_KEY}" \
  -d '{"query":"test","hitsPerPage":1}' | jq '{nbHits, processingTimeMS}'

# 4. Check index health
echo "Index stats:"
curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
  -H "X-Algolia-Application-Id:

                

              

                
                  
                  algolia-install-auth
                  View full skill →
                
                
                  Install and configure the Algolia JavaScript v5 client with proper API key management.
                  
                      ReadWriteEditBash(npm:*)Bash(pnpm:*)Bash(npx:*)Grep
                    
                
                
                  Algolia Install & Auth
Overview
Set up the algoliasearch v5 JavaScript client with Application ID and API key authentication. Algolia uses a two-key system: an Application ID (identifies your app) and an API key (controls permissions). Every Algolia account has three default keys: Search-Only, Admin, and Monitoring.
Prerequisites

Node.js 18+ with npm, pnpm, or yarn
Algolia account at dashboard.algolia.com
Application ID and API key from dashboard > Settings > API Keys

Instructions
Step 1: Install the Client

# Full client (Search + Analytics + Recommend + A/B Testing + Personalization)
npm install algoliasearch

# Or search-only (lighter bundle, frontend use)
npm install algoliasearch  # then import { liteClient } from 'algoliasearch/lite'

# Or individual API clients if you only need one
npm install @algolia/client-search
npm install @algolia/client-analytics
npm install @algolia/recommend

Step 2: Configure Environment Variables

# .env (NEVER commit — add to .gitignore)
ALGOLIA_APP_ID=YourApplicationID
ALGOLIA_ADMIN_KEY=your_admin_api_key
ALGOLIA_SEARCH_KEY=your_search_only_api_key

# .gitignore
.env
.env.local
.env.*.local

Key types and when to use them:

Key Type
ACL Permissions
Use In


Search-Only
search
Frontend, mobile apps


Admin
All operations
Backend only, never expose


Monitoring
GET /1/status
Health checks


Custom
You define ACL
Scoped backend services


Step 3: Initialize the Client

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

// Backend — Admin client for indexing operations
const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

// Frontend — Search-only client (safe to expose)
import { liteClient } from 'algoliasearch/lite';

const searchClient = liteClient(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!
);

Step 4: Verify Connection

// Quick verification: list indices
async function verifyAlgoliaConnection() {
  try {
    const { items } = await client.listIndices();
    console.log(`Connected. Found ${items.length} indices.`);
    return true;
  } catch (error) {
    console.error('Algolia connection failed:', error);
    return false;
  }
}

await verifyAlgoliaConnection();

Output
The project has a v5 Algolia 
                
              

                
                  
                  algolia-local-dev-loop
                  View full skill →
                
                
                  Configure Algolia local development with separate dev index, mocking, and testing.
                  
                      ReadWriteEditBash(npm:*)Bash(pnpm:*)Bash(npx:*)Grep
                    
                
                
                  Algolia Local Dev Loop
Overview
Set up a fast, reproducible local development workflow for Algolia. Use separate dev indices, mock the client in tests, and iterate without touching production data.
Prerequisites

Completed algolia-install-auth setup
Node.js 18+ with npm/pnpm
Vitest or Jest for testing

Instructions
Step 1: Environment-Based Index Names

// src/algolia/config.ts
import { algoliasearch } from 'algoliasearch';

const ENV = process.env.NODE_ENV || 'development';

// Each environment gets its own index prefix
export function indexName(base: string): string {
  if (ENV === 'production') return base;
  return `${ENV}_${base}`; // e.g., "development_products"
}

export const client = algoliasearch(
  process.env.ALGOLIA_APP_ID!,
  process.env.ALGOLIA_ADMIN_KEY!
);

Step 2: Seed Script for Dev Data

// scripts/seed-algolia.ts
import { client, indexName } from '../src/algolia/config';

const SEED_DATA = [
  { objectID: 'prod-1', name: 'Widget A', category: 'tools', price: 29.99 },
  { objectID: 'prod-2', name: 'Widget B', category: 'tools', price: 49.99 },
  { objectID: 'prod-3', name: 'Gadget C', category: 'electronics', price: 199.99 },
];

async function seed() {
  const idx = indexName('products');

  // replaceAllObjects atomically swaps index content
  const { taskID } = await client.replaceAllObjects({
    indexName: idx,
    objects: SEED_DATA,
  });
  await client.waitForTask({ indexName: idx, taskID });

  // Configure settings for the dev index
  await client.setSettings({
    indexName: idx,
    indexSettings: {
      searchableAttributes: ['name', 'category'],
      attributesForFaceting: ['category', 'filterOnly(price)'],
      customRanking: ['asc(price)'],
    },
  });

  console.log(`Seeded ${SEED_DATA.length} records into ${idx}`);
}

seed().catch(console.error);


{
  "scripts": {
    "seed:algolia": "npx tsx scripts/seed-algolia.ts",
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

Step 3: Mock Algolia in Unit Tests

// tests/algolia.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';

// Mock the entire algoliasearch module
vi.mock('algoliasearch', () => ({
  algoliasearch: vi.fn(() => ({
    searchSingleIndex: vi.fn().mockResolvedValue({
      hits: [
        { objectID: '1', name: 'Widget A', _highlightResult: {} },
      ],
      nbHits: 1,
      page: 0,
      nbPages: 1,
    })

                

              

                
                  
                  algolia-migration-deep-dive
                  View full skill →
                
                
                  Migrate to Algolia from Elasticsearch, Typesense, or Meilisearch.
                  
                      ReadWriteEditBash(npm:*)Bash(node:*)Bash(curl:*)
                    
                
                
                  Algolia Migration Deep Dive
Overview
Comprehensive guide for migrating from another search engine (Elasticsearch, Typesense, Meilisearch, or custom) to Algolia. Uses the strangler fig pattern: run old and new in parallel, gradually shift traffic, then cut over.
Prerequisites

A tested export of the source search data and a rollback owner for the cutover window.
An isolated target index or Algolia application for rehearsal.
Baseline relevance, latency, and record-count measurements for comparison after migration.

Migration Planning

From
Difficulty
Notes
Duration


Elasticsearch
Medium
query syntax differs significantly
2-4 weeks


Typesense
Low
similar hosted model
1-2 weeks


Meilisearch
Low
similar API concepts
1-2 weeks


Custom SQL LIKE
Low
major upgrade
1-2 weeks


Solr
Medium
config-heavy to API-driven
2-4 weeks


Instructions
Examples
The migration commands and comparison checks below illustrate a staged copy, validation, and cutover. Rehearse them against the target index before scheduling any production alias or frontend switch.
Step 1: Assess Current Implementation

# Find all search-related code
grep -rn "elasticsearch\|elastic\|typesense\|meilisearch\|\.search(" \
  --include="*.ts" --include="*.tsx" --include="*.js" src/ | wc -l

# Inventory current search features used
grep -rn "aggregations\|facets\|filters\|sort\|highlight\|suggest" \
  --include="*.ts" --include="*.tsx" src/


// Document current capabilities
interface MigrationAssessment {
  currentEngine: string;
  recordCount: number;
  indexCount: number;
  features: {
    fullTextSearch: boolean;
    faceting: boolean;
    filtering: boolean;
    geoSearch: boolean;
    synonyms: boolean;
    customRanking: boolean;
    analytics: boolean;
    abTesting: boolean;
    recommendations: boolean;
  };
  integrationPoints: string[];  // Files that call the search engine
  queryPatterns: string[];       // Types of queries used
}

Step 2: Create the Adapter Layer

// src/search/adapter.ts
// Abstraction layer — both engines implement the same interface

interface SearchResult<T> {
  hits: T[];
  totalHits: number;
  totalPages: number;
  currentPage: number;
  facets?: Record<string, Record<string, number>>;
  processingTimeMs: number;
}

interface SearchAdapter {
  search<T>(params: {
    index: string;
    query: string;
    filters?: st

                

              

                
                  
                  algolia-multi-env-setup
                  View full skill →
                
                
                  Configure Algolia across dev/staging/production: index prefixing, per-environment API keys, settings-as-code, and environment isolation guards.
                  
                      ReadWriteEditBash(npm:*)Bash(gcloud:*)Bash(vault:*)
                    
                
                
                  Algolia Multi-Environment Setup
Overview
Algolia doesn't have built-in environment separation. You either use separate Algolia applications (strongest isolation) or index prefixing within one application (simpler). This skill covers both approaches.
Prerequisites

Separate environment names or application credentials and a clear production promotion policy.
CI secrets scoped to the environment that performs indexing.
A naming convention that prevents a staging job from writing to the production index.

Environment Strategies

Strategy
Isolation
Cost
Complexity


Index prefixing
Shared app, prefixed names
Lowest
Low


Separate API keys
Shared app, scoped keys
Low
Medium


Separate applications
Full isolation
Highest
High


Instructions
Examples
The index-prefix and configuration examples below demonstrate environment isolation and controlled promotion. Keep the same convention in local tooling, CI, and runtime configuration to avoid cross-environment writes.
Step 1: Index Prefixing (Recommended for Most Teams)

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

type Environment = 'development' | 'staging' | 'production';

interface AlgoliaConfig {
  appId: string;
  apiKey: string;
  searchKey: string;
  environment: Environment;
}

function getConfig(): AlgoliaConfig {
  const env = (process.env.NODE_ENV || 'development') as Environment;

  return {
    appId: process.env.ALGOLIA_APP_ID!,
    apiKey: process.env.ALGOLIA_ADMIN_KEY!,
    searchKey: process.env.ALGOLIA_SEARCH_KEY!,
    environment: env,
  };
}

// Prefix index names with environment
export function indexName(base: string): string {
  const { environment } = getConfig();
  if (environment === 'production') return base;  // No prefix in prod
  return `${environment}_${base}`;
  // development_products, staging_products, products
}

let _client: Algoliasearch | null = null;

export function getClient(): Algoliasearch {
  if (!_client) {
    const config = getConfig();
    _client = algoliasearch(config.appId, config.apiKey);
  }
  return _client;
}

Step 2: Scoped API Keys Per Environment

import { algoliasearch } from 'algoliasearch';

const adminClient = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Create environment-scoped keys that can ONLY access their own indices
async function createEnvironmentKeys() {
  // Staging key: can only access staging_* indices
  const { key: stagingKey } = await ad

                

              

                
                  
                  algolia-observability
                  View full skill →
                
                
                  Set up observability for Algolia: Prometheus metrics for search latency/errors, OpenTelemetry tracing, structured logging, and Grafana dashboards.
                  
                      ReadWriteEdit
                    
                
                
                  Algolia Observability
Overview
Algolia provides built-in analytics in the dashboard, but production systems need application-level observability: latency histograms, error rate counters, distributed traces, and alerts. This skill instruments the algoliasearch v5 client with Prometheus, OpenTelemetry, and structured logging.
Prerequisites

Access to the application's metrics, tracing, and logging platform.
A stable service name and index labels that distinguish production from test traffic.
Permission to inspect Algolia request IDs and API responses without logging API keys or user PII.

Key Metrics to Track

Metric
Type
Why It Matters


Search latency (P50/P95/P99)
Histogram
User experience, SLA compliance


Search requests/sec
Counter
Capacity planning, cost tracking


Error rate by type
Counter
Detect API issues before users report


Index freshness (last updated)
Gauge
Data pipeline health


Record count
Gauge
Cost monitoring, data integrity


Instructions
Examples
The client wrapper, metrics endpoint, tracing, and alert examples below create a correlated view of search latency, errors, and index activity. Preserve request IDs and aggregate labels; never emit search credentials in telemetry.
Step 1: Instrumented Algolia Client Wrapper

// src/algolia/instrumented-client.ts
import { algoliasearch, ApiError } from 'algoliasearch';
import { Counter, Histogram, Gauge, Registry } from 'prom-client';

const registry = new Registry();

const searchLatency = new Histogram({
  name: 'algolia_search_duration_seconds',
  help: 'Algolia search request duration in seconds',
  labelNames: ['index', 'status'],
  buckets: [0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5],
  registers: [registry],
});

const searchTotal = new Counter({
  name: 'algolia_search_requests_total',
  help: 'Total Algolia search requests',
  labelNames: ['index', 'status'],
  registers: [registry],
});

const searchErrors = new Counter({
  name: 'algolia_errors_total',
  help: 'Total Algolia errors by type',
  labelNames: ['index', 'error_type', 'status_code'],
  registers: [registry],
});

const indexRecords = new Gauge({
  name: 'algolia_index_records',
  help: 'Number of records in Algolia index',
  labelNames: ['index'],
  registers: [registry],
});

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

export async function instrumentedSearch<T = any>(
  indexName: string,
  searchPa

                

              

                
                  
                  algolia-performance-tuning
                  View full skill →
                
                
                  Optimize Algolia search performance: record size, searchable attributes, replica strategy, response caching, and query-time parameter tuning.
                  
                      ReadWriteEdit
                    
                
                
                  Algolia Performance Tuning
Overview
Algolia's edge infrastructure typically delivers search in < 50ms globally. When performance degrades, the causes are usually: oversized records, too many searchable attributes, unoptimized faceting, or missing client-side caching. This skill covers server-side and client-side optimizations.
Prerequisites

Baseline search latency, relevance, payload size, and error-rate measurements from production-like traffic.
A representative test index and query corpus for evaluating changes before rollout.
Access to index settings and an owner for accepting relevance trade-offs.

Performance Baselines

Metric
Good
Warning
Action Needed


Search latency (P50)
< 20ms
20-100ms
> 100ms


Search latency (P95)
< 50ms
50-200ms
> 200ms


Indexing time per 1K records
< 2s
2-10s
> 10s


Record size (avg)
< 5KB
5-50KB
> 50KB


Instructions
Examples
The record, attribute, facet, cache, query, and replica examples below are measured tuning levers. Change one lever at a time and compare the stated baseline rather than optimizing for a synthetic request alone.
Step 1: Optimize Record Size

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// BAD: Full record with unnecessary data
const badRecord = {
  objectID: '1',
  name: 'Running Shoes',
  full_html_description: '<div>...5000 chars of HTML...</div>',  // Too big
  internal_notes: 'Supplier ref: ABC-123',                       // Not searchable
  all_reviews: [/* 200 reviews */],                                // Huge array
};

// GOOD: Lean record for search
const goodRecord = {
  objectID: '1',
  name: 'Running Shoes',
  description: 'Lightweight running shoes with cushioned sole',  // Plain text, truncated
  category: 'shoes',
  brand: 'Nike',
  price: 129.99,
  rating: 4.5,
  review_count: 200,          // Count, not full reviews
  in_stock: true,
  image_url: '/images/1.jpg', // URL, not base64
};

Step 2: Optimize Searchable Attributes

await client.setSettings({
  indexName: 'products',
  indexSettings: {
    // Order matters: first attribute = highest priority in ranking
    // Fewer searchable attributes = faster search
    searchableAttributes: [
      'name',                    // Highest priority
      'brand',
      'category',
      'unordered(description)

                

              

                
                  
                  algolia-prod-checklist
                  View full skill →
                
                
                  Execute Algolia production readiness checklist: index settings, key security, replica configuration, monitoring, and rollback procedures.
                  
                      ReadBash(curl:*)Bash(npm:*)Grep
                    
                
                
                  Algolia Production Checklist
Overview
Complete checklist for deploying Algolia search to production. Covers index configuration, API key security, replica setup, monitoring, and rollback procedures.
Prerequisites

A named production index, deployment owner, rollback decision maker, and change window.
Read-only verification credentials plus separate, least-privileged deployment credentials.
Current monitoring and alert destinations tested before the release begins.

Instructions
Run the checklist in order, record each result, and stop the deployment on any failed security, relevance, or availability requirement. Use the verification script only after every prerequisite configuration item is confirmed.
Examples
The checklist and pre-deploy script are the release example: run them against the intended production index and attach the results to the deployment record before enabling the new search experience.
Pre-Production Checklist
Index Configuration

[ ] searchableAttributes ordered by priority (first = highest)
[ ] attributesForFaceting set for all filterable attributes
[ ] customRanking configured (business metrics as tie-breakers)
[ ] unretrievableAttributes set for fields that should be searchable but not returned
[ ] attributesToRetrieve limited to fields needed by the UI
[ ] typoTolerance tested (default: enabled, min 4 chars for 1 typo, min 8 for 2)
[ ] removeStopWords configured for your language(s)
[ ] distinct set if deduplication needed (e.g., one result per product group)


// Verify production settings
const settings = await client.getSettings({ indexName: 'products' });
console.log(JSON.stringify(settings, null, 2));

API Key Security

[ ] Admin key in backend env vars only (never frontend)
[ ] Search-Only key used in frontend with referers restriction
[ ] maxQueriesPerIPPerHour set on all public keys
[ ] maxHitsPerQuery limited on search keys
[ ] Secured API keys used for multi-tenant data isolation
[ ] Keys restricted to specific indexes where possible

Replicas (Alternate Sorting)

// Replicas give users alternate sort orders
await client.setSettings({
  indexName: 'products',
  indexSettings: {
    // Standard replicas: share parent's data, use their own relevance settings
    replicas: [
      'products_price_asc',    // Sort by price ascending
      'products_price_desc',   // Sort by price descending
      'products_newest',       // Sort by newest first
    ],
  },
});

// 

                

              

                
                  
                  algolia-rate-limits
                  View full skill →
                
                
                  Handle Algolia rate limits and throttling: per-key limits, indexing queue limits, 429 responses, and backoff strategies.
                  
                      ReadWriteEdit
                    
                
                
                  Algolia Rate Limits
Overview
Algolia has two distinct rate limiting mechanisms: per-API-key limits (configurable, returns HTTP 429) and server-side indexing limits (protects cluster stability, returns HTTP 429 with specific messages). The algoliasearch v5 client has built-in retry with backoff, but you need to handle sustained rate limiting yourself.
Prerequisites

A current inventory of public and server-side API keys, expected request rates, and peak traffic sources.
Access to application metrics so 429 responses can be distinguished from client bugs or plan limits.
A safe test workload for verifying backoff and batch throttling without stressing production.

How Algolia Rate Limiting Works
Per-API-Key Rate Limits

Setting
Default
Where to Change


maxQueriesPerIPPerHour
0 (unlimited)
Dashboard > API Keys > Edit


maxHitsPerQuery
1000
Dashboard > API Keys > Edit


Search requests
Plan-dependent
Upgrade plan


Server-Side Indexing Limits
When the indexing queue is overloaded, Algolia returns 429 with these messages:

Message
Meaning
Action


Too many jobs
Queue full
Reduce batch frequency


Job queue too large
Too much pending work
Wait for queue to drain


Old jobs on the queue
Stuck tasks
Check dashboard > Indices > Operations


Disk almost full
Record quota near limit
Delete unused records or upgrade


Instructions
Examples
The key configuration, backoff, and batch-indexing examples show bounded responses to rate pressure. Use jittered retries and queue limits rather than retrying every rejected request immediately.
Step 1: Configure Per-Key Rate Limits

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Create a rate-limited API key for frontend use
const { key } = await client.addApiKey({
  apiKey: {
    acl: ['search'],
    description: 'Frontend search key — rate limited',
    maxQueriesPerIPPerHour: 1000,  // Per user IP
    maxHitsPerQuery: 20,
    indexes: ['products'],          // Restrict to specific indices
    validity: 0,                    // 0 = never expires
  },
});
console.log(`Created rate-limited key: ${key}`);

Step 2: Implement Backoff for Sustained 429s
                
              

                
                  
                  algolia-reference-architecture
                  View full skill →
                
                
                  Implement Algolia reference architecture: index design, multi-index strategy, data pipeline, search service layer, and frontend/backend separation.
                  
                      ReadGrep
                    
                
                
                  Algolia Reference Architecture
Overview
Production-ready architecture for Algolia-powered search. Covers index design, data pipeline from source to Algolia, service layer patterns, and frontend integration.
Prerequisites

A source-of-truth datastore, an approved transformation boundary, and explicit ownership for indexing and search-serving services.
Separate Admin and search-only credentials, kept on the backend and frontend respectively.
An environment and index naming convention that permits safe rehearsal and rollback.

Instructions
Use the architecture, project layout, and design patterns as a composable reference. Keep indexing, settings management, and search serving as separately testable boundaries rather than coupling them to a frontend component.
Examples
The diagrams and TypeScript patterns below demonstrate the reference topology, record transformation, settings-as-code, and service-layer contracts. Adapt the interfaces to your source schema while preserving the key boundary between write and search credentials.
Architecture Overview

┌──────────────────────────────────────────────────────────────┐
│                      Frontend                                 │
│  InstantSearch.js / React InstantSearch                       │
│  Uses: liteClient (search-only key)                          │
│  Sends: search-insights events (clicks, conversions)          │
└───────────────────────┬──────────────────────────────────────┘
                        │ Search + Events
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                   Algolia Cloud                               │
│  ┌─────────┐  ┌──────────────┐  ┌─────────────┐             │
│  │ Search   │  │ Analytics    │  │ Recommend   │             │
│  │ Engine   │  │ + Insights   │  │ (ML-based)  │             │
│  └─────────┘  └──────────────┘  └─────────────┘             │
└───────────────────────▲──────────────────────────────────────┘
                        │ Indexing (admin key)
                        │
┌──────────────────────────────────────────────────────────────┐
│                    Backend Service                            │
│  ┌────────────┐  ┌──────────────┐  ┌─────────────────┐      │
│  │ Search     │  │ Indexing     │  │ Settings        │      │
│  │ Service    │  │ Pipeline     │  │ Manager         │      │
│  └────────────┘  └──────┬───────┘  └─────────────────┘      │
│                         │                                     │
│  ┌──────────────────────▼────────────────────────────┐       │
│  │              Source Database                        │       │
│  │  PostgreSQL / MongoDB / CMS / External API          │       │
│  └────────────────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────────────┘

Project Structure

                
              

                
                  
                  algolia-sdk-patterns
                  View full skill →
                
                
                  Apply production-ready algoliasearch v5 patterns: singleton client, typed search, error handling, and batch operations.
                  
                      ReadWriteEdit
                    
                
                
                  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
export function resetClient(): void {
  _client = null;
}

Pattern 2: Typed Search Results

// src/algolia/types.ts

// Define your record shape — extends Algolia's Hit type
interface Product {
  objectID: string;
  name: string;
  category: string;
  price: number;
  description: string;
  image_url: string;
}

// src/algolia/search.ts
import { getClient } from './client';

export async function searchProducts(
  query: string,
  options?: {
    filters?: string;
    facetFilters?: string[][];
    hitsPerPage?: number;
    page?: number;
  }
) {
  const client = getClient();

  const { hits, nbHits, nbPages, page } = await client.searchSingleIndex<Product>({
    indexName: 'products',
    searchParams: {
      query,
      filters: options?.filters,
      facetFilters: options?.facetFilters,
      hitsPerPage: options?.hitsPerPage ?? 20,
      page: options?.page ?? 0,
      attributesToRetrieve: ['name', 'category', 'price', 'image_url'],
      attributesToHighlight: ['name', 'description'],
    },
  });

  return { hits, totalHits: nbHits, totalPages: nbPages, currentPage: page };
}

// Usage: const { hits } = await searchProducts('laptop', { filters: 'price < 1000' });

Pattern 3: Error Handling with Algolia Error Types

// src/algolia/errors.ts
import { ApiError } from 'algoliasearch'

                

              

                
                  
                  algolia-security-basics
                  View full skill →
                
                
                  Apply Algolia security best practices: API key scoping, secured API keys, frontend vs backend key separation, and key rotation.
                  
                      ReadWriteEditGrep
                    
                
                
                  Algolia Security Basics
Overview
Algolia's security model is built around scoped API keys. Every Algolia app has three default keys (Admin, Search-Only, Monitoring). For production, create custom keys with minimal permissions and use Secured API Keys for per-user/per-tenant restrictions.
Prerequisites

An inventory of current API keys, their consumers, and the indices each consumer needs.
A secure secret store and a tested rotation process for backend credentials.
Authority to revoke or restrict exposed keys immediately if the audit finds a violation.

Key Types and Where to Use Them

Key Type
ACL
Expose to Frontend?
Use Case


Admin
All operations
NEVER
Backend indexing, settings, key management


Search-Only
search only
Yes (safe)
Frontend search widgets


Monitoring
Read monitoring data
No
Health checks, dashboards


Custom
You define ACL
Depends on ACL
Scoped backend services


Secured
Derived from parent key
Yes
Per-user filtered search


Instructions
Examples
The environment, scoped-key, secured-key, and rotation examples demonstrate least privilege at each trust boundary. Replace placeholder values through the secret store and validate the resulting ACL before a client receives the key.
Step 1: Environment Variable Setup

# .env (NEVER commit — add to .gitignore)
ALGOLIA_APP_ID=YourApplicationID
ALGOLIA_ADMIN_KEY=admin_api_key_here        # Backend only
ALGOLIA_SEARCH_KEY=search_only_key_here     # OK for frontend

# .gitignore — MUST include:
.env
.env.local
.env.*.local

Step 2: Create Scoped API Keys

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Create a write-only key for a specific microservice
const { key: indexingKey } = await client.addApiKey({
  apiKey: {
    acl: ['addObject', 'deleteObject', 'editSettings'],
    description: 'Product sync service — write only',
    indexes: ['products', 'products_staging'],  // Restrict to specific indices
    maxQueriesPerIPPerHour: 5000,
    referers: [],  // Empty = no referer restriction (backend use)
  },
});

// Create a search key restricted to specific referers (frontend)
const { key: frontendKey } = await client.addApiKey({
  apiKey: {
    acl: ['search'],
    description: 'Frontend search — domain-restricted',
    indexes: ['products'],
    referers: ['ht

                

              

                
                  
                  algolia-upgrade-migration
                  View full skill →
                
                
                  Upgrade algoliasearch from v4 to v5 with breaking change detection and codemod.
                  
                      ReadWriteEditBash(npm:*)Bash(git:*)Bash(npx:*)Grep
                    
                
                
                  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
Examples
The upgrade steps are concrete v4-to-v5 examples: replace client initialization and method calls, then run the search and type-check suite before widening rollout. Keep the pre-upgrade branch available until production verification succeeds.
Step 1: Create Upgrade Branch and Install v5

git checkout -b upgrade/a

                

              

                
                  
                  algolia-webhooks-events
                  View full skill →
                
                
                  Implement Algolia Insights API for click/conversion tracking, search analytics, and real-time event-driven index updates via database change listeners.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)
                    
                
                
                  Algolia Events & Insights
Overview
Algolia doesn't use traditional webhooks. Instead, it provides the Insights API for sending user behavior events (clicks, conversions, views) back to Algolia, and the Analytics API for reading search performance data. For keeping your index in sync, you build event-driven pipelines from your database to Algolia.
Prerequisites

algoliasearch v5 installed (Insights client is included)
Index with records and queryID enabled (for click analytics)
search-insights npm package for frontend event tracking

Instructions
Examples
The search, Insights, analytics, and database-sync snippets below show the event correlation contract end to end. Preserve the query ID and a stable user token, and route failed source-database events to a retryable queue rather than dropping them.
Step 1: Enable Click Analytics in Search

import { algoliasearch } from 'algoliasearch';

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_ADMIN_KEY!);

// Enable clickAnalytics to get queryID in search results
const { hits, queryID } = await client.searchSingleIndex({
  indexName: 'products',
  searchParams: {
    query: 'running shoes',
    clickAnalytics: true,  // Returns queryID for event correlation
  },
});
// queryID links this search to subsequent click/conversion events

Step 2: Send Click and Conversion Events (Backend)

// The Insights API is built into the algoliasearch client
// Events connect user behavior back to specific search queries

// Track a click on a search result
await client.pushEvents({
  events: [{
    eventType: 'click',
    eventName: 'Product Clicked',
    index: 'products',
    userToken: 'user-123',        // Unique user identifier
    queryID: queryID,              // From search response
    objectIDs: ['product-456'],    // What was clicked
    positions: [3],                // Position in results (1-indexed)
    timestamp: Date.now(),
  }],
});

// Track a conversion (purchase, add-to-cart)
await client.pushEvents({
  events: [{
    eventType: 'conversion',
    eventName: 'Product Purchased',
    index: 'products',
    userToken: 'user-123',
    queryID: queryID,
    objectIDs: ['product-456'],
    timestamp: Date.now(),
  }],
});

// Track a view (product page visit, no search context)
await client.pushEvents({
  events: [{
    eventType: 'view',
    eventName: 'Product Viewed',
    index: 'products',
    userToken: 'user-123',
    objectIDs: ['product-456'],
    timestamp: Date.now(),
  }],
});

Step 3: Frontend Event Tracking with search-insights

                
              
          

        


      
      
          How It Works
          Skills trigger automatically when you discuss Algolia topics:

"Help me set up Algolia" -> algolia-install-auth
"Search not returning results" -> algolia-common-errors
"Migrate from Elasticsearch" -> algolia-migration-deep-dive
"Optimize Algolia costs" -> algolia-cost-tuning

        

      
      

      
      

      
      
  Ready to use algolia-pack?
  
    
    
  




      
      
          Related Plugins
          
            
  supabase-pack
  Complete Supabase integration skill pack with 30 skills covering authentication, database, storage, realtime, edge functions, and production operations. Flagship+ tier vendor pack.
  /plugin install supabase-pack@claude-code-plugins-plus
  

  vercel-pack
  Complete Vercel integration skill pack with 30 skills covering deployments, edge functions, preview environments, performance optimization, and production operations. Flagship+ tier vendor pack.
  /plugin install vercel-pack@claude-code-plugins-plus
  

  clay-pack
  Complete Clay integration skill pack with 30 skills covering data enrichment, waterfall workflows, AI agents, and GTM automation. Flagship+ tier vendor pack.
  /plugin install clay-pack@claude-code-plugins-plus
  

  cursor-pack
  Complete Cursor integration skill pack with 30 skills covering AI code editing, composer workflows, codebase indexing, and productivity features. Flagship+ tier vendor pack.
  /plugin install cursor-pack@claude-code-plugins-plus
  

  exa-pack
  Complete Exa integration skill pack with 30 skills covering neural search, semantic retrieval, web search API, and AI-powered discovery. Flagship+ tier vendor pack.
  /plugin install exa-pack@claude-code-plugins-plus
  

  firecrawl-pack
  Complete Firecrawl integration skill pack with 30 skills covering web scraping, crawling, markdown conversion, and LLM-ready data extraction. Flagship+ tier vendor pack.
  /plugin install firecrawl-pack@claude-code-plugins-plus
  

          
        

      
      
          Tags
          
            algoliasaassdkintegration
          
        
    

  

  

    

    
    
        
            
                Agent Skills in Your Inbox
                
                    
                    
                    
                
                No spam, ever. Unsubscribe with one click.
            

            
                
                    Product
                    
                        Explore
                        Skills
                        Cowork
                        Compare
                        Tools
                    
                
                
                    Resources
                    
                        Docs
                        Changelog
                        Collections
                        Playbooks
                        Research
                        Learning
                    
                
                
                    Company
                    
                        Community
                        Hall of Fame
                        GitHub
                    
                
                
                    Legal
                    
                        Privacy
                        Terms
                        Acceptable Use
                    
                
            

            
            

            
                Tons of Skills by Intent Solutions. Open-source plugins, agents and skills for AI coding agents.
                © 2026 Tons of Skills | Intent Solutions

Plan	Records Included	Search Requests	Additional Cost
Build (Free)	1M records	10K requests/mo	N/A
Grow	100K free, then $0.40/1K	10K free, then $0.50/1K	Pay as you go
Grow Plus	100K free, then $0.40/1K	10K free, then $1.75/1K	+ AI features
Premium	Custom	Custom	Volume discounts

ACL	Operations Allowed	Use For
`search`	Search queries	Frontend, search-only clients
`browse`	Browse/export all records	Data export, migration scripts
`addObject`	Add or replace records	Indexing pipelines
`deleteObject`	Delete records	Data cleanup, GDPR deletion
`editSettings`	Modify index settings	Deployment scripts
`listIndexes`	List all indices	Monitoring, health checks
`deleteIndex`	Delete entire indices	Admin operations only
`analytics`	Read analytics data	Dashboards, reporting
`recommendation`	Algolia Recommend API	Product recommendations
`usage`	Read usage data	Billing monitoring
`logs`	Read API logs	Debugging, audit