Integrate Algolia Search into React and Next.js Apps

This skill provides expert patterns for Algolia search, indexing, React InstantSearch, and relevance tuning, across seven concrete areas. React InstantSearch with hooks covers the react-instantsearch-hooks-web and react-instantsearch packages built on an algoliasearch client, with widgets like SearchBox, Hits, and Configure and hooks useSearchBox, useHits, useRefinementList, usePagination, and useInstantSearch for full state access. Next.js SSR requires swapping InstantSearch for InstantSearchNext, from react-instantsearch-nextjs, supporting both Pages and App Router, setting dynamic='force-dynamic' for fresh results per request, and using a routing prop plus getServerState for URL-synced initial state. Data synchronization covers three sync strategies, full reindexing, full record updates, and partial updates via partialUpdateObjects for attribute-only changes, recommending 10MB or 1K-10K record batches, incremental updates over deleteBy, and a zero-downtime full reindex via a temp index, copyIndex to carry over settings, synonyms, and rules, and an atomic moveIndex swap. API key security distinguishes Admin keys, full control, Search-Only keys, safe for frontend, and Secured keys generated from a base key with restrictions, indices, rate limit, validity, HTTP referrers, query parameters, illustrated via generateSecuredApiKey with per-user filters plus a validUntil expiry, and addApiKey with maxQueriesPerIPPerHour for public endpoints. Relevance tuning covers ordering searchableAttributes by importance, title and name first, description last, adding customRanking with desc() or asc() on business metrics like popularity, rating, or date, typo tolerance thresholds, minWordSizefor1Typo and minWordSizefor2Typos, synonyms including one-way synonyms, query-based rules such as boosting sale items via a contains-pattern condition, and attributeForDistinct-based deduplication; dates must be indexed as timestamps rather than raw date strings, since strings can't be sorted correctly. Faceted search covers RefinementList, Menu, HierarchicalMenu with nested category levels, RangeInput and RangeSlider, and ToggleRefinement widgets, plus sorting via separate replica indices with their own customRanking; attributes must be explicitly declared in attributesForFaceting before they can be faceted on, and filterOnly() should be used for facets that only filter results without being shown to the user, since a plain facet declaration wastes computation displaying options nobody sees. Autocomplete covers both @algolia/autocomplete-js standalone widgets, with query-suggestions and instant-results sources, and InstantSearch's built-in Autocomplete component, noting that Query Suggestions requires a separate index Algolia generates from search analytics.

export const searchClient = algoliasearch(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!  // Search-only key!
);

Ten named sharp edges flag where implementations typically break: Admin API Key in Frontend Code, CRITICAL, Indexing Rate Limits and Throttling, HIGH, Record Size and Index Limits, PII in Index Names Visible in Network, Searchable Attributes Order Affects Relevance, Full Reindex Consumes All Operations, Every Keystroke Counts as a Search Operation, SSR Hydration Mismatch with InstantSearch, and Faceting Requires attributesForFaceting Declaration, all MEDIUM, and Replica Indices for Sorting Multiply Storage, LOW. A distinct validation rule not covered by the pattern-level anti-patterns: using a search-only key for indexing operations is flagged as an error, since indexing requires the admin key specifically.

It also routes adjacent needs to sibling skills: e-commerce checkout to stripe-integration, search analytics to segment-cdp, user authentication, for per-user secured keys, to clerk-auth, database setup to postgres-wizard, and serverless indexing jobs to aws-serverless.

Use this skill when adding search, InstantSearch, a search API, typeahead or autocomplete, or faceted search to an application. It is not for the adjacent concerns it explicitly delegates, checkout flows, search analytics, authentication, the source database, or serverless deployment, each has its own dedicated skill.

Input is the Algolia search feature being built: a React or Next.js search UI, an indexing pipeline, API key configuration, relevance tuning, faceted filters, or autocomplete. Output is working code, client setup, index configuration, secured-key generation, widget wiring, plus the specific anti-pattern to avoid for that feature, grounded in the searchable-attributes, customRanking, synonyms, and rules mechanisms Algolia actually exposes.

Algolia's JavaScript and Node client, algoliasearch and algoliasearch/lite, react-instantsearch and react-instantsearch-nextjs, @algolia/autocomplete-js, and Next.js's App and Pages routers and dynamic-rendering config; delegates to stripe-integration, segment-cdp, clerk-auth, postgres-wizard, and aws-serverless for adjacent concerns.

Frontend and full-stack developers implementing Algolia search, instant search UIs, faceted navigation, autocomplete, relevance tuning, or the indexing pipeline and API-key security behind them.