Algolia Install & Auth

Overview

Set up the

algoliasearch

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:

search

GET /1/status

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();

Error Handling

Invalid Application-ID or API key

Index does not exist

saveObjects

Method not allowed

RetryError: Unreachable hosts

*.algolia.net

*.algolianet.com

Record quota exceeded

Examples

Singleton Pattern (Recommended)

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

let _client: Algoliasearch | null = null;

export function getAlgoliaClient(): Algoliasearch {
  if (!_client) {
    const appId = process.env.ALGOLIA_APP_ID;
    const apiKey = process.env.ALGOLIA_ADMIN_KEY;
    if (!appId || !apiKey) {
      throw new Error('Missing ALGOLIA_APP_ID or ALGOLIA_ADMIN_KEY env vars');
    }
    _client = algoliasearch(appId, apiKey);
  }
  return _client;
}

Generate Scoped API Key (Secured API Key)

import { algoliasearch } from 'algoliasearch';

// Generate a secured API key that restricts search to specific filters
const client = algoliasearch(appId, adminKey);

const securedKey = client.generateSecuredApiKey({
  parentApiKey: searchOnlyKey,
  restrictions: {
    filters: 'tenant_id:acme_corp',
    validUntil: Math.floor(Date.now() / 1000) + 3600, // 1 hour
    restrictIndices: ['products_acme'],
  },
});

Resources

• Algolia JavaScript v5 Client
• API Keys Guide
• Secured API Keys
• Algolia Dashboard

Next Steps

After successful auth, proceed to

algolia-hello-world