Guia prático para implementar busca Algolia com Claude Code

O que decidir antes de programar

Algolia é um SaaS de busca que armazena registros otimizados em um índice e retorna resultados em milissegundos. Para um site pequeno, uma consultaLIKEno banco pode bastar. Mas tolerância a erros, facetas, ranking, sinônimos, analytics de cliques e busca multilíngue tornam a manutenção manual pesada.

Claude Code ajuda porque pode ler schema, rotas, componentes, regras de permissão e modelo de conteúdo antes de gerar código. O objetivo não é apenas criar uma barra de busca. É alinhar formato do registro, configurações do índice, pipeline de indexação, chaves seguras, UI com InstantSearch, eventos de analytics e revisão de relevância.

Este guia usa Algolia JavaScript API Client v5. Na v5, o padrão antigoinitIndexfoi removido; os métodos ficam no cliente e recebemindexName, comoclient.saveObjectseclient.searchSingleIndex. Consulte tambémJavaScript API Client v5, API clients e oscommon workflows do Claude Code.

Três casos de uso práticos

Separar o caso de uso evita um índice genérico demais.

Caso de uso	Dados	Configurações importantes	Risco principal
Busca de documentação	artigos, títulos, corpo, tags	searchableAttributes, sinônimos, destaque	indexar rascunhos ou notas internas
Catálogo de produtos ou cursos	nome, categoria, preço, estoque, popularidade	facets, customRanking, Insights	preço ou estoque desatualizado
Base de conhecimento interna	FAQ, tickets, notas técnicas	secured API key, filters, campos de permissão	vazamento de registros privados

No ClaudeCodeLab, o mesmo desenho serve para busca de artigos públicos, material de treinamento e templates. Antes da UI, defina quem pode ver cada resultado, quais atributos afetam o ranking e quais buscas devem levar a treinamento, templates ou consultoria.

Registro de busca mínimo e seguro

Não copie linhas completas do banco para o Algolia. Indexe apenas campos públicos que serão exibidos e metadados mínimos para ranking e filtros. E-mails, IDs de pagamento, notas internas, conteúdo não publicado e respostas brutas de API ficam fora.

{
  "objectID": "article_pt_claude-code-algolia-search",
  "title": "Guia prático para implementar busca Algolia com Claude Code",
  "summary": "Guia de índice, UI, analytics e ciclo de revisão",
  "content": "Texto pesquisável extraído apenas de conteúdo publicado",
  "locale": "pt",
  "section": "blog",
  "category": "use-cases",
  "tags": ["Claude Code", "Algolia", "busca"],
  "visibility": "public",
  "allowedTeams": [],
  "slug": "claude-code-algolia-search",
  "url": "/pt/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.webp"
}

MantenhaobjectIDestável. Se ele mudar a cada alteração de título ou URL, analytics e ajustes de relevância perdem continuidade. Para artigos,article_locale_slugfunciona bem.

Script de indexação com Algolia v5

Instale as dependências.

npm install algoliasearch@5 dotenv

ColoqueALGOLIA_APP_ID, ALGOLIA_ADMIN_KEYe opcionalmenteALGOLIA_INDEX_NAMEno.env. A chave admin deve ficar somente no servidor.

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

type SearchRecord = {
  objectID: string;
  title: string;
  summary: string;
  content: string;
  locale: "pt" | "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_pt_claude-code-algolia-search",
    title: "Guia prático para implementar busca Algolia com Claude Code",
    summary: "Guia de índice, UI, analytics e ciclo de revisão",
    content: "Indexe apenas texto pesquisável extraído de conteúdo publicado.",
    locale: "pt",
    section: "blog",
    category: "use-cases",
    tags: ["Claude Code", "Algolia", "busca"],
    visibility: "public",
    allowedTeams: [],
    slug: "claude-code-algolia-search",
    url: "/pt/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.webp"
  }
];

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", "código Claude"]
    },
    {
      objectID: "search-pt",
      type: "synonym",
      synonyms: ["busca", "pesquisa", "busca interna", "busca full-text"]
    }
  ],
  clearExistingSynonyms: true
});

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

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

Os campos mais importantes ficam no topo desearchableAttributes. Campos de permissão devem usarfilterOnly, restringindo resultados sem aparecer como facetas visíveis.

Endpoint de busca e secured API key

O navegador pode usar uma search-only key para busca pública. Nunca exponha admin key nem chaves com escrita. Para limitar resultados por usuário ou equipe, gere uma secured API key no servidor. A documentação oficial deAPI keys explica o modelo.

// 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 });
}

Se preferir busca pelo servidor, valide a entrada e retorne somente atributos seguros. VejaSearch 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") ?? "pt";

  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 com InstantSearch

InstantSearch.js fornece widgets para caixa de busca, facetas, destaque, estatísticas e paginação.

// 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:pt"
        clickAnalytics
      />
      <SearchBox placeholder="Buscar artigos de Claude Code" />
      <Stats />
      <div className="mt-6 grid gap-6 md:grid-cols-[220px_1fr]">
        <aside>
          <h2 className="text-sm font-bold">Categoria</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 e revisão

Busca boa melhora por ciclo: consultas, buscas sem resultado, posição de clique, conversões e mudanças controladas em registros, settings, sinônimos e UI.

// 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]
  });
}

Use Claude Code como revisor com critérios explícitos.

Você é o revisor de qualidade de busca do ClaudeCodeLab.
Revise consultas Algolia, buscas sem resultado, top 10, CTR e conversões.

Saída:
| query | problema | causa | alteração proposta | risco | prioridade |

Regras:
- Não adicione campos privados ao índice.
- Separe mudanças em settings, synonyms, record content e UI.
- Verifique se o artigo esperado está no top 3.
- Decida entre sinônimo, título, corpo ou facet.
- Confira se CTAs de treinamento, templates e consultoria batem com a intenção.

Armadilhas comuns

A primeira é expor a chave errada. Tudo comNEXT_PUBLIC_vai para o navegador. Ali só deve existir search-only key ou secured API key gerada no servidor.

A segunda é indexar demais. Se um campo privado entrou no Algolia, assuma que ele pode ser recuperado. Limpe registros e reduzaattributesToRetrieve.

A terceira é ranking por intuição. Comece por título e resumo, useconversionScore, popularitye atualização como desempate, e revise semanalmente com Insights.

A quarta é exagerar em sinônimos. Relacionar “AI”, “Claude” e “ChatGPT” sem evidência confunde intenção. Adicione sinônimos quando os logs mostrarem buscas sem resultado ou variações reais.

A quinta é testar antes da conclusão da tarefa. Após settings, sinônimos ou registros, aguardewaitForTask.

Conectar com monetização

Busca também faz parte do funil. “Algolia search” deve levar a este guia; “CLAUDE.md template” deve apontar paratemplates CLAUDE.md; dúvidas de adoção em equipe podem ir paraconsultoria ClaudeCodeLab. Inclua também oguia de funcionalidade de busca eotimização de performance.

ClaudeCodeLab pode apoiar treinamento em Claude Code, templates de prompt e CLAUDE.md, e consultoria de implementação. Antes de codar, liste campos públicos, critérios de ranking e consultas com intenção comercial.

Resumo

Claude Code e Algolia funcionam melhor quando busca vira ciclo de produto: registros seguros, chaves separadas, ranking claro, indexação sincronizada, UI útil, analytics e revisão contínua.

Ao testar o fluxo deste artigo, a maior redução de retrabalho veio de limitar campos eattributesToRetrievedesde o início. O prompt de revisão com Claude Code também facilitou tratar, na mesma rotina, buscas sem resultado, sinônimos, ajustes de conteúdo e CTAs para treinamento, templates e consultoria.