Algolia Search System

A Claude Code skill for integrating Algolia's search-as-a-service platform into your application. Covers index configuration, React InstantSearch implementation, faceted filtering, relevance tuning, and search analytics for building fast, typo-tolerant search experiences.

When to Use This Skill

Choose Algolia Search System when:

• You need to add fast, typo-tolerant search to your application
• You want faceted filtering and search-as-you-type functionality
• You're implementing Algolia with React InstantSearch
• You need to configure Algolia indices for optimal relevance
• You want to add search analytics and A/B testing

Consider alternatives when:

• You want open-source search (use Elasticsearch or Meilisearch)
• You need database full-text search (use PostgreSQL FTS)
• You want AI-powered semantic search (use a vector search solution)

Quick Start

Copy
# Install Algolia packages
npm install algoliasearch react-instantsearch

# Install the skill
claude install algolia-search-system

# Set up Algolia search
claude "Set up Algolia search for my Next.js e-commerce site with product search, category filtering, and price range"

# Configure index
claude "Configure my Algolia index for blog posts: searchable attributes, custom ranking, and facets"

Core Concepts

React InstantSearch Setup

Copy
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, SearchBox, Hits, RefinementList } from 'react-instantsearch';

const searchClient = algoliasearch('APP_ID', 'SEARCH_API_KEY');

function Search() {
  return (
    <InstantSearch searchClient={searchClient} indexName="products">
      <SearchBox placeholder="Search products..." />
      <RefinementList attribute="category" />
      <Hits hitComponent={ProductHit} />
    </InstantSearch>
  );
}

Index Configuration

Setting	Purpose	Example
Searchable Attributes	Which fields to search	["name", "description", "category"]
Custom Ranking	Business metric ranking	["desc(popularity)", "desc(rating)"]
Facets	Filterable attributes	["category", "brand", "price"]
Synonyms	Alternative search terms	["laptop", "notebook", "computer"]
Stop Words	Words to ignore	["the", "a", "is"]

InstantSearch Widgets

Widget	Purpose	Usage
SearchBox	Text input for queries	Main search input
Hits	Display search results	Result list/grid
RefinementList	Checkbox facet filters	Category, brand filtering
RangeSlider	Numeric range filter	Price range
Pagination	Page navigation	Result pagination
Stats	Result count display	"42 results found"
SortBy	Sort order selector	Relevance, price, date

Configuration

Parameter	Type	Default	Description
framework	string	"react"	Framework: react, vue, angular, vanilla
index_name	string	""	Algolia index name
searchable_fields	string[]	[]	Fields to search
facets	string[]	[]	Filterable attributes
records_per_page	number	20	Results per page

Best Practices

1. Order searchable attributes by priority — Put the most important fields first: ["name", "title", "description", "tags"]. Algolia ranks matches in earlier attributes higher. A match in the product name should rank above a match in the description.

2. Use custom ranking to inject business logic — After relevance, rank by your business metrics: popularity, sales count, rating. This ensures that relevant results are also commercially valuable. Configure in the Algolia dashboard or via API.

3. Keep records small — Only index the fields you need for search and display. Don't index large description fields unless they're searchable. Smaller records mean faster search and lower costs.

4. Use server-side API key with rate limiting — Never expose your Admin API key on the client. Use a Search-Only API key for frontend search. For sensitive operations (indexing, settings), use server-side code with the Admin key.

5. Sync data proactively — Keep your Algolia index in sync with your database. Use webhooks or change data capture to update the index when records change. Stale search results frustrate users.

Common Issues

Search results don't match expectations — Check your searchable attributes ordering and custom ranking configuration. Use the Algolia dashboard's search preview to test queries and see why results rank the way they do.

Slow initial render — Algolia search is fast, but the first render can feel slow if you're loading the InstantSearch bundle. Use dynamic imports to lazy-load InstantSearch widgets and show a search skeleton until ready.

Facet counts are wrong — Facet counts are calculated based on the current search context, not the total dataset. This is expected behavior — it shows how many results exist within the current filtered view.