| name | algolia-search |
| description | Expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, and relevance tuning |
| risk | unknown |
| source | vibeship-spawner-skills (Apache 2.0) |
| date_added | "2026-02-27T00:00:00.000Z" |
Algolia Search Integration
Expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, and relevance tuning
Patterns
React InstantSearch with Hooks
Modern React InstantSearch setup using hooks for type-ahead search.
Uses react-instantsearch-hooks-web package with algoliasearch client.
Widgets are components that can be customized with classnames.
Key hooks:
- useSearchBox: Search input handling
- useHits: Access search results
- useRefinementList: Facet filtering
- usePagination: Result pagination
- useInstantSearch: Full state access
Code_example
// lib/algolia.ts
import algoliasearch from 'algoliasearch/lite';
export const searchClient = algoliasearch(
process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY! // Search-only key!
);
export const INDEX_NAME = 'products';
// components/Search.tsx
'use client';
import { InstantSearch, SearchBox, Hits, Configure } from 'react-instantsearch';
import { searchClient, INDEX_NAME } from '@/lib/algolia';
function Hit({ hit }: { hit: ProductHit }) {
return (
{hit.name}
{hit.description}
${hit.price}
);
}
export function ProductSearch() {
return (
<SearchBox
placeholder="Search products..."
classNames={{
root: 'relative',
input: 'w-full px-4 py-2 border rounded',
}}
/>
);
}
// Custom hook usage
import { useSearchBox, useHits, useInstantSearch } from 'react-instantsearch';
function CustomSearch() {
const { query, refine } = useSearchBox();
const { hits } = useHits();
const { status } = useInstantSearch();
return (
<input
value={query}
onChange={(e) => refine(e.target.value)}
placeholder="Search..."
/>
{status === 'loading' &&
Loading...
}
{hits.map((hit) => (
- {hit.name}
))}
);
}
Anti_patterns
- Pattern: Using Admin API key in frontend code | Why: Admin key exposes full index control including deletion | Fix: Use search-only API key with restrictions
- Pattern: Not using /lite client for frontend | Why: Full client includes unnecessary code for search | Fix: Import from algoliasearch/lite for smaller bundle
References
Next.js Server-Side Rendering
SSR integration for Next.js with react-instantsearch-nextjs package.
Use instead of for SSR.
Supports both Pages Router and App Router (experimental).
Key considerations:
- Set dynamic = 'force-dynamic' for fresh results
- Handle URL synchronization with routing prop
- Use getServerState for initial state
Code_example
// app/search/page.tsx
import { InstantSearchNext } from 'react-instantsearch-nextjs';
import { searchClient, INDEX_NAME } from '@/lib/algolia';
import { SearchBox, Hits, RefinementList } from 'react-instantsearch';
// Force dynamic rendering for fresh search results
export const dynamic = 'force-dynamic';
export default function SearchPage() {
return (
<InstantSearchNext
searchClient={searchClient}
indexName={INDEX_NAME}
routing={{
router: {
cleanUrlOnDispose: false,
},
}}
>
Categories
Brand
);
}
// For custom routing (URL synchronization)
import { history } from 'instantsearch.js/es/lib/routers';
import { simple } from 'instantsearch.js/es/lib/stateMappings';
<InstantSearchNext
searchClient={searchClient}
indexName={INDEX_NAME}
routing={{
router: history({
getLocation: () =>
typeof window === 'undefined'
? new URL(url) as unknown as Location
: window.location,
}),
stateMapping: simple(),
}}
{/* widgets */}
Anti_patterns
- Pattern: Using InstantSearch component for Next.js SSR | Why: Regular component doesn't support server-side rendering | Fix: Use InstantSearchNext from react-instantsearch-nextjs
- Pattern: Static rendering for search pages | Why: Search results must be fresh for each request | Fix: Set export const dynamic = 'force-dynamic'
References
Data Synchronization and Indexing
Indexing strategies for keeping Algolia in sync with your data.
Three main approaches:
- Full Reindexing - Replace entire index (expensive)
- Full Record Updates - Replace individual records
- Partial Updates - Update specific attributes only
Best practices:
- Batch records (ideal: 10MB, 1K-10K records per batch)
- Use incremental updates when possible
- partialUpdateObjects for attribute-only changes
- Avoid deleteBy (computationally expensive)
Code_example
// lib/algolia-admin.ts (SERVER ONLY)
import algoliasearch from 'algoliasearch';
// Admin client - NEVER expose to frontend
const adminClient = algoliasearch(
process.env.ALGOLIA_APP_ID!,
process.env.ALGOLIA_ADMIN_KEY! // Admin key for indexing
);
const index = adminClient.initIndex('products');
// Batch indexing (recommended approach)
export async function indexProducts(products: Product[]) {
const records = products.map((p) => ({
objectID: p.id, // Required unique identifier
name: p.name,
description: p.description,
price: p.price,
category: p.category,
inStock: p.inventory > 0,
createdAt: p.createdAt.getTime(), // Use timestamps for sorting
}));
// Batch in chunks of ~1000-5000 records
const BATCH_SIZE = 1000;
for (let i = 0; i < records.length; i += BATCH_SIZE) {
const batch = records.slice(i, i + BATCH_SIZE);
await index.saveObjects(batch);
}
}
// Partial update - update only specific fields
export async function updateProductPrice(productId: string, price: number) {
await index.partialUpdateObject({
objectID: productId,
price,
updatedAt: Date.now(),
});
}
// Partial update with operations
export async function incrementViewCount(productId: string) {
await index.partialUpdateObject({
objectID: productId,
viewCount: {
_operation: 'Increment',
value: 1,
},
});
}
// Delete records (prefer this over deleteBy)
export async function deleteProducts(productIds: string[]) {
await index.deleteObjects(productIds);
}
// Full reindex with zero-downtime (atomic swap)
export async function fullReindex(products: Product[]) {
const tempIndex = adminClient.initIndex('products_temp');
// Index to temp index
await tempIndex.saveObjects(
products.map((p) => ({
objectID: p.id,
...p,
}))
);
// Copy settings from main index
await adminClient.copyIndex('products', 'products_temp', {
scope: ['settings', 'synonyms', 'rules'],
});
// Atomic swap
await adminClient.moveIndex('products_temp', 'products');
}
Anti_patterns
- Pattern: Using deleteBy for bulk deletions | Why: deleteBy is computationally expensive and rate limited | Fix: Use deleteObjects with array of objectIDs
- Pattern: Indexing one record at a time | Why: Creates indexing queue, slows down process | Fix: Batch records in groups of 1K-10K
- Pattern: Full reindex for small changes | Why: Wastes operations, slower than incremental | Fix: Use partialUpdateObject for attribute changes
References
API Key Security and Restrictions
Secure API key configuration for Algolia.
Key types:
- Admin API Key: Full control (indexing, settings, deletion)
- Search-Only API Key: Safe for frontend
- Secured API Keys: Generated from base key with restrictions
Restrictions available:
- Indices: Limit accessible indices
- Rate limit: Limit API calls per hour per IP
- Validity: Set expiration time
- HTTP referrers: Restrict to specific URLs
- Query parameters: Enforce search parameters
Code_example
// NEVER do this - admin key in frontend
// const client = algoliasearch(appId, ADMIN_KEY); // WRONG!
// Correct: Use search-only key in frontend
const searchClient = algoliasearch(
process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!
);
// Server-side: Generate secured API key
// lib/algolia-secured-key.ts
import algoliasearch from 'algoliasearch';
const adminClient = algoliasearch(
process.env.ALGOLIA_APP_ID!,
process.env.ALGOLIA_ADMIN_KEY!
);
// Generate user-specific secured key
export function generateSecuredKey(userId: string) {
const searchKey = process.env.ALGOLIA_SEARCH_KEY!;
return adminClient.generateSecuredApiKey(searchKey, {
// User can only see their own data
filters: userId:${userId},
// Key expires in 1 hour
validUntil: Math.floor(Date.now() / 1000) + 3600,
// Restrict to specific index
restrictIndices: ['user_documents'],
});
}
// Rate-limited key for public APIs
export async function createRateLimitedKey() {
const { key } = await adminClient.addApiKey({
acl: ['search'],
indexes: ['products'],
description: 'Public search with rate limit',
maxQueriesPerIPPerHour: 1000,
referers: ['https://mysite.com/*'],
validity: 0, // Never expires
});
return key;
}
// API endpoint to get user's secured key
// app/api/search-key/route.ts
import { auth } from '@/lib/auth';
import { generateSecuredKey } from '@/lib/algolia-secured-key';
export async function GET() {
const session = await auth();
if (!session?.user) {
return Response.json({ error: 'Unauthorized' }, { status: 401 });
}
const securedKey = generateSecuredKey(session.user.id);
return Response.json({ key: securedKey });
}
Anti_patterns
- Pattern: Hardcoding Admin API key in client code | Why: Exposes full index control to attackers | Fix: Use search-only key with restrictions
- Pattern: Using same key for all users | Why: Can't restrict data access per user | Fix: Generate secured API keys with user filters
- Pattern: No rate limiting on public search | Why: Bots can exhaust your search quota | Fix: Set maxQueriesPerIPPerHour on API key
References
Custom Ranking and Relevance Tuning
Configure searchable attributes and custom ranking for relevance.
Searchable attributes (order matters):
- Most important fields first (title, name)
- Secondary fields next (description, tags)
- Exclude non-searchable fields (image_url, id)
Custom ranking:
- Add business metrics (popularity, rating, date)
- Use desc() for descending, asc() for ascending
Code_example
// scripts/configure-index.ts
import algoliasearch from 'algoliasearch';
const adminClient = algoliasearch(
process.env.ALGOLIA_APP_ID!,
process.env.ALGOLIA_ADMIN_KEY!
);
const index = adminClient.initIndex('products');
async function configureIndex() {
await index.setSettings({
// Searchable attributes in order of importance
searchableAttributes: [
'name', // Most important
'brand',
'category',
'description', // Least important
],
// Attributes for faceting/filtering
attributesForFaceting: [
'category',
'brand',
'filterOnly(inStock)', // Filter only, not displayed
'searchable(tags)', // Searchable facet
],
// Custom ranking (after text relevance)
customRanking: [
'desc(popularity)', // Most popular first
'desc(rating)', // Then by rating
'desc(createdAt)', // Then by recency
],
// Typo tolerance
typoTolerance: true,
minWordSizefor1Typo: 4,
minWordSizefor2Typos: 8,
// Query settings
queryLanguages: ['en'],
removeStopWords: ['en'],
// Highlighting
attributesToHighlight: ['name', 'description'],
highlightPreTag: '<mark>',
highlightPostTag: '</mark>',
// Pagination
hitsPerPage: 20,
paginationLimitedTo: 1000,
// Distinct (deduplication)
attributeForDistinct: 'productFamily',
distinct: true,
});
// Add synonyms
await index.saveSynonyms([
{
objectID: 'phone-mobile',
type: 'synonym',
synonyms: ['phone', 'mobile', 'cell', 'smartphone'],
},
{
objectID: 'laptop-notebook',
type: 'oneWaySynonym',
input: 'laptop',
synonyms: ['notebook', 'portable computer'],
},
]);
// Add rules (query-based customization)
await index.saveRules([
{
objectID: 'boost-sale-items',
condition: {
anchoring: 'contains',
pattern: 'sale',
},
consequence: {
params: {
filters: 'onSale:true',
optionalFilters: ['featured:true'],
},
},
},
]);
console.log('Index configured successfully');
}
configureIndex();
Anti_patterns
- Pattern: Searching all attributes equally | Why: Reduces relevance, matches in descriptions rank same as titles | Fix: Order searchableAttributes by importance
- Pattern: No custom ranking | Why: Relies only on text matching, ignores business value | Fix: Add popularity, rating, or recency to customRanking
- Pattern: Indexing raw dates as strings | Why: Can't sort by date correctly | Fix: Use timestamps (getTime()) for date sorting
References
Faceted Search and Filtering
Implement faceted navigation with refinement lists, range sliders,
and hierarchical menus.
Widget types:
- RefinementList: Multi-select checkboxes
- Menu: Single-select list
- HierarchicalMenu: Nested categories
- RangeInput/RangeSlider: Numeric ranges
- ToggleRefinement: Boolean filters
Code_example
'use client';
import {
InstantSearch,
SearchBox,
Hits,
RefinementList,
HierarchicalMenu,
RangeInput,
ToggleRefinement,
ClearRefinements,
CurrentRefinements,
Stats,
SortBy,
} from 'react-instantsearch';
import { searchClient, INDEX_NAME } from '@/lib/algolia';
export function ProductSearch() {
return (
{/* Filters Sidebar */}
{/* Category hierarchy */}
<div>
<h3 className="font-semibold mb-2">Categories</h3>
<HierarchicalMenu
attributes={[
'categories.lvl0',
'categories.lvl1',
'categories.lvl2',
]}
limit={10}
showMore
/>
</div>
{/* Brand filter */}
<div>
<h3 className="font-semibold mb-2">Brand</h3>
<RefinementList
attribute="brand"
searchable
searchablePlaceholder="Search brands..."
showMore
limit={5}
showMoreLimit={20}
/>
</div>
{/* Price range */}
<div>
<h3 className="font-semibold mb-2">Price</h3>
<RangeInput
attribute="price"
precision={0}
classNames={{
input: 'w-20 px-2 py-1 border rounded',
}}
/>
</div>
{/* In stock toggle */}
<ToggleRefinement
attribute="inStock"
label="In Stock Only"
on={true}
/>
{/* Rating filter */}
<div>
<h3 className="font-semibold mb-2">Rating</h3>
<RefinementList
attribute="rating"
transformItems={(items) =>
items.map((item) => ({
...item,
label: '★'.repeat(Number(item.label)),
}))
}
/>
</div>
</aside>
{/* Results */}
<main className="flex-1">
<div className="flex justify-between items-center mb-4">
<SearchBox placeholder="Search products..." />
<SortBy
items={[
{ label: 'Relevance', value: 'products' },
{ label: 'Price (Low to High)', value: 'products_price_asc' },
{ label: 'Price (High to Low)', value: 'products_price_desc' },
{ label: 'Rating', value: 'products_rating_desc' },
]}
/>
</div>
<Stats />
<Hits hitComponent={ProductHit} />
</main>
</div>
</InstantSearch>
);
}
// For sorting, create replica indices
// products_price_asc: customRanking: ['asc(price)']
// products_price_desc: customRanking: ['desc(price)']
// products_rating_desc: customRanking: ['desc(rating)']
Anti_patterns
- Pattern: Faceting on non-faceted attributes | Why: Must declare attributesForFaceting in settings | Fix: Add attributes to attributesForFaceting array
- Pattern: Not using filterOnly() for hidden filters | Why: Wastes facet computation on non-displayed attributes | Fix: Use filterOnly(attribute) for filters you won't show
References
Query Suggestions and Autocomplete
Implement autocomplete with query suggestions and instant results.
Uses @algolia/autocomplete-js for standalone autocomplete or
integrate with InstantSearch using SearchBox.
Query Suggestions require a separate index generated by Algolia.
Code_example
// Standalone Autocomplete
// components/Autocomplete.tsx
'use client';
import { autocomplete, getAlgoliaResults } from '@algolia/autocomplete-js';
import algoliasearch from 'algoliasearch/lite';
import { useEffect, useRef } from 'react';
import '@algolia/autocomplete-theme-classic';
const searchClient = algoliasearch(
process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!
);
export function Autocomplete() {
const containerRef = useRef(null);
useEffect(() => {
if (!containerRef.current) return;
const search = autocomplete({
container: containerRef.current,
placeholder: 'Search for products',
openOnFocus: true,
getSources({ query }) {
if (!query) return [];
return [
// Query suggestions
{
sourceId: 'suggestions',
getItems() {
return getAlgoliaResults({
searchClient,
queries: [
{
indexName: 'products_query_suggestions',
query,
params: { hitsPerPage: 5 },
},
],
});
},
templates: {
header() {
return 'Suggestions';
},
item({ item, html }) {
return html`<span>${item.query}</span>`;
},
},
},
// Instant results
{
sourceId: 'products',
getItems() {
return getAlgoliaResults({
searchClient,
queries: [
{
indexName: 'products',
query,
params: { hitsPerPage: 8 },
},
],
});
},
templates: {
header() {
return 'Products';
},
item({ item, html }) {
return html`
<a href="/products/${item.objectID}">
<img src="${item.image}" alt="${item.name}" />
<span>${item.name}</span>
<span>$${item.price}</span>
</a>
`;
},
},
onSelect({ item, setQuery, refresh }) {
// Navigate on selection
window.location.href = `/products/${item.objectID}`;
},
},
];
},
});
return () => search.destroy();
}, []);
return
;
}
// Combined with InstantSearch
import { connectSearchBox } from 'react-instantsearch';
import { autocomplete } from '@algolia/autocomplete-js';
// Or use built-in Autocomplete widget
import { Autocomplete as AlgoliaAutocomplete } from 'react-instantsearch';
export function SearchWithAutocomplete() {
return (
);
}
Anti_patterns
- Pattern: Creating autocomplete without debouncing | Why: Every keystroke triggers search, wastes operations | Fix: Algolia autocomplete handles debouncing automatically
- Pattern: Not using Query Suggestions index | Why: Missing search analytics for popular queries | Fix: Enable Query Suggestions in Algolia dashboard
References
Sharp Edges
Admin API Key in Frontend Code
Severity: CRITICAL
Indexing Rate Limits and Throttling
Severity: HIGH
Record Size and Index Limits
Severity: MEDIUM
PII in Index Names Visible in Network
Severity: MEDIUM
Searchable Attributes Order Affects Relevance
Severity: MEDIUM
Full Reindex Consumes All Operations
Severity: MEDIUM
Every Keystroke Counts as Search Operation
Severity: MEDIUM
SSR Hydration Mismatch with InstantSearch
Severity: MEDIUM
Replica Indices for Sorting Multiply Storage
Severity: LOW
Faceting Requires attributesForFaceting Declaration
Severity: MEDIUM
Validation Checks
Admin API Key in Client Code
Severity: ERROR
Admin API key must never be exposed to client-side code
Message: Admin API key exposed to client. Use search-only key.
Hardcoded Algolia API Key
Severity: ERROR
API keys should use environment variables
Message: Hardcoded Algolia credentials. Use environment variables.
Search Key Used for Indexing
Severity: ERROR
Indexing operations require admin key, not search key
Message: Search key used for indexing. Use admin key for write operations.
Single Record Indexing in Loop
Severity: WARNING
Batch records together for efficient indexing
Message: Single record indexing in loop. Use saveObjects for batch indexing.
Using deleteBy for Deletion
Severity: WARNING
deleteBy is expensive and rate-limited
Message: deleteBy is expensive. Prefer deleteObjects with specific IDs.
Frequent Full Reindex
Severity: WARNING
Full reindex wastes operations on unchanged data
Message: Frequent full reindex. Consider incremental sync for unchanged data.
Full Client Instead of Lite
Severity: INFO
Use lite client for smaller bundle in frontend
Message: Full Algolia client imported. Use algoliasearch/lite for frontend.
Regular InstantSearch in Next.js
Severity: WARNING
Use react-instantsearch-nextjs for SSR support
Message: Using regular InstantSearch. Use InstantSearchNext for Next.js SSR.
Missing Searchable Attributes Configuration
Severity: WARNING
Configure searchableAttributes for better relevance
Message: No searchableAttributes configured. Set attribute priority for relevance.
Missing Custom Ranking
Severity: INFO
Custom ranking improves business relevance
Message: No customRanking configured. Add business metrics (popularity, rating).
Collaboration
Delegation Triggers
- user needs e-commerce checkout -> stripe-integration (Product search leading to purchase)
- user needs search analytics -> segment-cdp (Track search queries and results)
- user needs user authentication -> clerk-auth (Secured API keys per user)
- user needs database setup -> postgres-wizard (Source data for indexing)
- user needs serverless deployment -> aws-serverless (Lambda for indexing jobs)
When to Use
- User mentions or implies: adding search to
- User mentions or implies: algolia
- User mentions or implies: instantsearch
- User mentions or implies: search api
- User mentions or implies: search functionality
- User mentions or implies: typeahead
- User mentions or implies: autocomplete search
- User mentions or implies: faceted search
- User mentions or implies: search index
- User mentions or implies: search as you type
