Guide pratique pour implémenter Algolia avec Claude Code

Les décisions à prendre avant de coder

Algolia est un SaaS de recherche qui stocke des enregistrements optimisés dans un index et renvoie les résultats en quelques millisecondes. Une requêteLIKEpeut suffire pour un petit site, mais la tolérance aux fautes, les facettes, le ranking, les synonymes, les analytics de clics et le multilingue deviennent vite lourds à maintenir soi-même.

Claude Code est utile parce qu’il peut lire votre schéma, vos routes, vos composants, vos règles d’accès et votre modèle de contenu avant de générer du code. L’objectif n’est pas seulement de créer un champ de recherche, mais d’aligner la forme des enregistrements, les paramètres d’index, le pipeline d’indexation, les clés sécurisées, l’UI InstantSearch, les événements analytics et la revue de pertinence.

Ce guide utilise Algolia JavaScript API Client v5. En v5, l’ancien modèleinitIndexa disparu : les méthodes vivent sur le client et reçoiventindexName, par exempleclient.saveObjectsetclient.searchSingleIndex. Consultez la documentation officielleJavaScript API Client v5, API clients et lescommon workflows de Claude Code.

Trois cas d’usage concrets

Séparer les cas d’usage évite de créer un index trop vague.

Cas d’usage	Données	Réglages importants	Risque principal
Recherche documentaire	articles, titres, contenu, tags	searchableAttributes, synonymes, surbrillance	indexer des brouillons ou notes internes
Catalogue produit ou formation	nom, catégorie, prix, stock, popularité	facets, customRanking, Insights	prix ou disponibilité obsolètes
Base de connaissance interne	FAQ, tickets, notes de conception	secured API key, filters, champs de permissions	fuite de données privées

Pour ClaudeCodeLab, la même logique sert à rechercher les articles publics, les supports de formation et les modèles. Avant l’UI, décidez qui peut voir quoi, quels attributs influencent le ranking et quelles requêtes doivent mener vers la formation, les templates ou la consultation.

Un enregistrement de recherche minimal

Ne copiez pas des lignes complètes de base de données dans Algolia. Indexez seulement les champs publics affichables et les métadonnées minimales nécessaires au ranking et au filtrage. Les emails, identifiants de paiement, notes internes, contenus non publiés et réponses API brutes doivent rester hors de l’index.

{
  "objectID": "article_fr_claude-code-algolia-search",
  "title": "Guide pratique pour implémenter Algolia avec Claude Code",
  "summary": "Guide sur l'index, l'UI, les analytics et la revue de pertinence",
  "content": "Texte recherchable extrait uniquement du contenu publié",
  "locale": "fr",
  "section": "blog",
  "category": "use-cases",
  "tags": ["Claude Code", "Algolia", "recherche"],
  "visibility": "public",
  "allowedTeams": [],
  "slug": "claude-code-algolia-search",
  "url": "/fr/blog/claude-code-algolia-search",
  "publishedAt": "2025-11-15",
  "updatedAt": "2026-06-01",
  "updatedAtTimestamp": 1780272000,
  "popularity": 42,
  "conversionScore": 7,
  "readingMinutes": 12,
  "thumbnail": "/images/hero/hero-090.png"
}

GardezobjectIDstable. Si l’identifiant change à chaque modification du titre ou de l’URL, les analytics et les ajustements de pertinence perdent leur continuité. Un format commearticle_locale_slugest simple pour les articles.

Script d’indexation avec Algolia v5

Installez les dépendances.

npm install algoliasearch@5 dotenv

PlacezALGOLIA_APP_ID, ALGOLIA_ADMIN_KEYet éventuellementALGOLIA_INDEX_NAMEdans.env. La clé admin reste côté serveur uniquement.

// scripts/index-articles.ts
import "dotenv/config";
import { algoliasearch } from "algoliasearch";

type SearchRecord = {
  objectID: string;
  title: string;
  summary: string;
  content: string;
  locale: "fr" | "en";
  section: "blog" | "docs" | "product";
  category: string;
  tags: string[];
  visibility: "public" | "restricted";
  allowedTeams: string[];
  slug: string;
  url: string;
  publishedAt: string;
  updatedAt: string;
  updatedAtTimestamp: number;
  popularity: number;
  conversionScore: number;
  readingMinutes: number;
  thumbnail: string;
};

const appId = process.env.ALGOLIA_APP_ID;
const adminKey = process.env.ALGOLIA_ADMIN_KEY;
const indexName = process.env.ALGOLIA_INDEX_NAME ?? "claudecodelab_articles";

if (!appId || !adminKey) {
  throw new Error("ALGOLIA_APP_ID and ALGOLIA_ADMIN_KEY are required");
}

const client = algoliasearch(appId, adminKey);

const records: SearchRecord[] = [
  {
    objectID: "article_fr_claude-code-algolia-search",
    title: "Guide pratique pour implémenter Algolia avec Claude Code",
    summary: "Guide sur l'index, l'UI, les analytics et la revue de pertinence",
    content: "Indexez uniquement le texte recherchable extrait du contenu publié.",
    locale: "fr",
    section: "blog",
    category: "use-cases",
    tags: ["Claude Code", "Algolia", "recherche"],
    visibility: "public",
    allowedTeams: [],
    slug: "claude-code-algolia-search",
    url: "/fr/blog/claude-code-algolia-search",
    publishedAt: "2025-11-15",
    updatedAt: "2026-06-01",
    updatedAtTimestamp: 1780272000,
    popularity: 42,
    conversionScore: 7,
    readingMinutes: 12,
    thumbnail: "/images/hero/hero-090.png"
  }
];

await client.setSettings({
  indexName,
  indexSettings: {
    searchableAttributes: [
      "unordered(title)",
      "unordered(summary)",
      "content",
      "tags",
      "category"
    ],
    attributesForFaceting: [
      "filterOnly(visibility)",
      "filterOnly(locale)",
      "filterOnly(allowedTeams)",
      "searchable(category)",
      "searchable(tags)",
      "section"
    ],
    customRanking: [
      "desc(conversionScore)",
      "desc(popularity)",
      "desc(updatedAtTimestamp)"
    ],
    attributesToRetrieve: [
      "title",
      "summary",
      "locale",
      "section",
      "category",
      "tags",
      "url",
      "updatedAt",
      "thumbnail"
    ],
    attributesToHighlight: ["title", "summary", "content"],
    typoTolerance: true,
    removeWordsIfNoResults: "lastWords"
  }
});

await client.saveSynonyms({
  indexName,
  synonymHit: [
    {
      objectID: "claude-code-names",
      type: "synonym",
      synonyms: ["Claude Code", "claude code", "code Claude"]
    },
    {
      objectID: "search-fr",
      type: "synonym",
      synonyms: ["recherche", "recherche interne", "moteur de recherche"]
    }
  ],
  clearExistingSynonyms: true
});

const { taskID } = await client.saveObjects({
  indexName,
  objects: records
});

await client.waitForTask({ indexName, taskID });
console.log(`Indexed ${records.length} records into ${indexName}`);

Les champs en haut desearchableAttributessont les plus importants. Les champs de permission doivent rester enfilterOnlypour filtrer sans devenir des facettes visibles.

Endpoint de recherche et secured API key

Le navigateur peut utiliser une search-only key pour une recherche publique. Il ne doit jamais recevoir de clé admin ni de clé d’écriture. Pour restreindre les résultats par utilisateur ou équipe, générez une secured API key côté serveur. Le guide officielAPI keys détaille ce mécanisme.

// app/api/search-key/route.ts
import { algoliasearch } from "algoliasearch";
import { NextResponse } from "next/server";

const appId = process.env.ALGOLIA_APP_ID!;
const searchKey = process.env.ALGOLIA_SEARCH_KEY!;
const indexName = process.env.ALGOLIA_INDEX_NAME ?? "claudecodelab_articles";

export async function GET() {
  const user = { id: "user_123", teamIds: ["training"] };
  const client = algoliasearch(appId, searchKey);

  const securedApiKey = client.generateSecuredApiKey({
    parentApiKey: searchKey,
    restrictions: {
      restrictIndices: indexName,
      filters: `visibility:public OR allowedTeams:${user.teamIds[0]}`,
      userToken: user.id,
      validUntil: Math.floor(Date.now() / 1000) + 60 * 30
    }
  });

  return NextResponse.json({ appId, indexName, apiKey: securedApiKey });
}

Si vous préférez une recherche côté serveur, validez l’entrée et retournez seulement des attributs sûrs. La référence estSearch an index.

// 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_SEARCH_KEY!
);
const indexName = process.env.ALGOLIA_INDEX_NAME ?? "claudecodelab_articles";

export async function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get("q")?.slice(0, 80) ?? "";
  const locale = request.nextUrl.searchParams.get("locale") ?? "fr";

  const result = await client.searchSingleIndex({
    indexName,
    searchParams: {
      query,
      filters: `visibility:public AND locale:${locale}`,
      hitsPerPage: 10,
      attributesToRetrieve: ["title", "summary", "url", "category", "tags"],
      clickAnalytics: true
    }
  });

  return NextResponse.json({
    hits: result.hits,
    queryID: result.queryID,
    nbHits: result.nbHits
  });
}

UI avec InstantSearch

InstantSearch.js fournit les widgets de recherche, facettes, statistiques, pagination et surbrillance.

// components/ArticleSearch.tsx
"use client";

import { liteClient as algoliasearch } from "algoliasearch/lite";
import {
  Configure,
  Highlight,
  Hits,
  InstantSearch,
  Pagination,
  RefinementList,
  SearchBox,
  Stats
} from "react-instantsearch";

type HitProps = {
  hit: {
    objectID: string;
    title: string;
    summary: string;
    url: string;
    category: string;
    tags: string[];
    updatedAt: string;
  };
};

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

function HitCard({ hit }: HitProps) {
  return (
    <article className="rounded border p-4">
      <a href={hit.url} className="font-bold">
        <Highlight attribute="title" hit={hit} />
      </a>
      <p className="mt-2 text-sm text-gray-600">
        <Highlight attribute="summary" hit={hit} />
      </p>
      <p className="mt-2 text-xs text-gray-500">
        {hit.category} · {hit.updatedAt}
      </p>
    </article>
  );
}

export function ArticleSearch() {
  return (
    <InstantSearch searchClient={searchClient} indexName="claudecodelab_articles">
      <Configure
        hitsPerPage={8}
        filters="visibility:public AND locale:fr"
        clickAnalytics
      />
      <SearchBox placeholder="Rechercher des articles Claude Code" />
      <Stats />
      <div className="mt-6 grid gap-6 md:grid-cols-[220px_1fr]">
        <aside>
          <h2 className="text-sm font-bold">Catégorie</h2>
          <RefinementList attribute="category" searchable />
          <h2 className="mt-4 text-sm font-bold">Tags</h2>
          <RefinementList attribute="tags" searchable />
        </aside>
        <main>
          <Hits hitComponent={HitCard} />
          <Pagination className="mt-6" />
        </main>
      </div>
    </InstantSearch>
  );
}

Analytics et revue de pertinence

Une recherche s’améliore avec les données : requêtes, recherches sans résultat, position du clic, conversions et corrections ciblées. AvecclickAnalytics, les résultats contiennent unqueryIDque vous pouvez associer aux clics.

// lib/search-insights.ts
import aa from "search-insights";

aa("init", {
  appId: process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  apiKey: process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!,
  useCookie: true
});

export function trackSearchClick(params: {
  indexName: string;
  objectID: string;
  queryID: string;
  position: number;
}) {
  aa("clickedObjectIDsAfterSearch", {
    eventName: "Article Clicked",
    index: params.indexName,
    queryID: params.queryID,
    objectIDs: [params.objectID],
    positions: [params.position]
  });
}

Demandez à Claude Code une revue structurée.

Tu es le reviewer qualité de recherche de ClaudeCodeLab.
Analyse les requêtes Algolia, les recherches sans résultat, le top 10,
le taux de clic et les conversions.

Sortie:
| query | problème | cause | changement proposé | risque | priorité |

Règles:
- N'ajoute aucun champ privé à l'index.
- Sépare les changements en settings, synonyms, record content et UI.
- Vérifie si l'article attendu est dans le top 3.
- Choisis entre synonyme, réécriture de titre, contenu ou facet.
- Vérifie si les CTA formation, templates et consultation correspondent à l'intention.

Pièges fréquents

Le premier piège est l’exposition de clé. Toute variableNEXT_PUBLIC_part dans le navigateur. Elle ne doit contenir qu’une search-only key ou une secured API key générée côté serveur.

Le deuxième est l’indexation excessive. Si un champ privé entre dans Algolia, considérez qu’il peut être récupéré. Nettoyez les enregistrements et limitezattributesToRetrieve.

Le troisième est le ranking au feeling. Priorisez titre et résumé, puis utilisezconversionScore, popularityet fraîcheur comme départage. Ajustez chaque semaine avec Insights.

Le quatrième est l’abus de synonymes. Relier trop largement “AI”, “Claude” et “ChatGPT” brouille l’intention. Ajoutez des synonymes seulement avec des preuves dans les logs.

Le cinquième est de tester trop tôt. Après settings, synonymes ou enregistrements, attendezwaitForTask.

Relier la recherche à la monétisation

La recherche fait partie du parcours commercial. “Algolia search” doit mener à ce guide, “CLAUDE.md template” auxtemplates CLAUDE.md, et les requêtes d’adoption d’équipe à laconsultation ClaudeCodeLab. Ajoutez aussi des liens vers leguide de fonctionnalité de recherche et l’optimisation des performances.

ClaudeCodeLab peut accompagner la formation Claude Code, les templates de prompts et CLAUDE.md, ainsi que la consultation d’implémentation. Avant de coder, listez les champs publics, les critères de ranking et les requêtes à forte intention.

Résumé

Claude Code et Algolia donnent de bons résultats quand la recherche est traitée comme une boucle produit : enregistrements sûrs, clés séparées, ranking clair, indexation synchronisée, UI utile, analytics et revue régulière.

Après avoir testé le flux décrit ici, la plus grande réduction de reprises vient du fait de limiter dès le départ les champs indexés etattributesToRetrieve. Le prompt de revue Claude Code aide aussi à traiter ensemble les recherches sans résultat, les synonymes, les contenus à réécrire et les CTA vers formation, templates et consultation.