From algolia-pack
Implements Algolia reference architecture: index design, multi-index strategy, data pipelines from PostgreSQL/MongoDB, search service layer, and React InstantSearch frontend integration.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin algolia-packThis skill is limited to using the following tools:
Production-ready architecture for Algolia-powered search. Covers index design, data pipeline from source to Algolia, service layer patterns, and frontend integration.
Provides patterns for Algolia search implementation using React InstantSearch hooks, indexing strategies, relevance tuning, and Next.js SSR integration.
Configures Algolia for dev/staging/prod environments using index prefixing, scoped API keys, settings-as-code, and isolation in TypeScript/Node.js apps.
Provides expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, relevance tuning, autocomplete, typeahead, and faceted search.
Share bugs, ideas, or general feedback.
Production-ready architecture for Algolia-powered search. Covers index design, data pipeline from source to Algolia, service layer patterns, and frontend integration.
┌──────────────────────────────────────────────────────────────┐
│ Frontend │
│ InstantSearch.js / React InstantSearch │
│ Uses: liteClient (search-only key) │
│ Sends: search-insights events (clicks, conversions) │
└───────────────────────┬──────────────────────────────────────┘
│ Search + Events
▼
┌──────────────────────────────────────────────────────────────┐
│ Algolia Cloud │
│ ┌─────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ Search │ │ Analytics │ │ Recommend │ │
│ │ Engine │ │ + Insights │ │ (ML-based) │ │
│ └─────────┘ └──────────────┘ └─────────────┘ │
└───────────────────────▲──────────────────────────────────────┘
│ Indexing (admin key)
│
┌──────────────────────────────────────────────────────────────┐
│ Backend Service │
│ ┌────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ Search │ │ Indexing │ │ Settings │ │
│ │ Service │ │ Pipeline │ │ Manager │ │
│ └────────────┘ └──────┬───────┘ └─────────────────┘ │
│ │ │
│ ┌──────────────────────▼────────────────────────────┐ │
│ │ Source Database │ │
│ │ PostgreSQL / MongoDB / CMS / External API │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
src/
├── algolia/
│ ├── client.ts # Singleton client (see algolia-sdk-patterns)
│ ├── indices.ts # Index name constants + environment prefixing
│ ├── settings/
│ │ ├── products.ts # Products index settings
│ │ ├── articles.ts # Articles index settings
│ │ └── apply.ts # Script to apply all settings
│ └── transforms/
│ ├── product.ts # DB record → Algolia record transformer
│ └── article.ts # DB record → Algolia record transformer
├── services/
│ ├── search.ts # Search service (wraps Algolia client)
│ └── indexing.ts # Indexing pipeline (DB → transform → Algolia)
├── api/
│ ├── search.ts # Search endpoint (returns Algolia results)
│ └── reindex.ts # Admin endpoint to trigger reindex
└── jobs/
└── sync-algolia.ts # Cron job for periodic full sync
// src/algolia/indices.ts
const ENV = process.env.NODE_ENV === 'production' ? '' : `${process.env.NODE_ENV}_`;
export const INDICES = {
products: `${ENV}products`,
articles: `${ENV}articles`,
faq: `${ENV}faq`,
users: `${ENV}users`, // Internal search only (never expose to frontend)
} as const;
export type IndexName = typeof INDICES[keyof typeof INDICES];
// src/algolia/transforms/product.ts
import type { Product } from '../db/types';
interface AlgoliaProduct {
objectID: string;
name: string;
description: string;
category: string;
brand: string;
price: number;
rating: number;
review_count: number;
in_stock: boolean;
image_url: string;
_tags: string[]; // Algolia convention: filterable tags
}
export function transformProduct(product: Product): AlgoliaProduct {
return {
objectID: product.id,
name: product.name,
description: product.description?.substring(0, 5000) || '', // Truncate
category: product.category.name,
brand: product.brand.name,
price: product.price / 100, // Cents → dollars
rating: product.avgRating,
review_count: product.reviewCount,
in_stock: product.inventory > 0,
image_url: product.images[0]?.url || '',
_tags: [
product.category.slug,
...(product.isFeatured ? ['featured'] : []),
...(product.isNew ? ['new-arrival'] : []),
],
};
}
// src/algolia/settings/products.ts
import type { IndexSettings } from 'algoliasearch';
export const productSettings: IndexSettings = {
searchableAttributes: [
'name',
'brand',
'category',
'unordered(description)',
],
attributesForFaceting: [
'searchable(brand)',
'category',
'filterOnly(price)',
'filterOnly(in_stock)',
'_tags',
],
customRanking: ['desc(review_count)', 'desc(rating)'],
attributesToRetrieve: ['name', 'brand', 'price', 'image_url', 'category', 'rating'],
attributesToHighlight: ['name', 'description'],
attributesToSnippet: ['description:30'],
unretrievableAttributes: ['_tags'],
distinct: 1,
attributeForDistinct: 'product_group_id',
replicas: [
'virtual(products_price_asc)',
'virtual(products_price_desc)',
'virtual(products_newest)',
],
};
// src/algolia/settings/apply.ts
import { getClient } from '../client';
import { INDICES } from '../indices';
import { productSettings } from './products';
async function applyAllSettings() {
const client = getClient();
await client.setSettings({ indexName: INDICES.products, indexSettings: productSettings });
console.log('All Algolia settings applied');
}
// src/services/search.ts
import { getClient } from '../algolia/client';
import { INDICES } from '../algolia/indices';
import { ApiError } from 'algoliasearch';
export class SearchService {
private client = getClient();
async searchProducts(params: {
query: string;
filters?: string;
facetFilters?: string[][];
page?: number;
hitsPerPage?: number;
}) {
try {
return await this.client.searchSingleIndex({
indexName: INDICES.products,
searchParams: {
query: params.query,
filters: params.filters,
facetFilters: params.facetFilters,
page: params.page ?? 0,
hitsPerPage: params.hitsPerPage ?? 20,
facets: ['category', 'brand'],
clickAnalytics: true,
},
});
} catch (error) {
if (error instanceof ApiError && error.status === 404) {
return { hits: [], nbHits: 0, nbPages: 0, page: 0 };
}
throw error;
}
}
async federatedSearch(query: string) {
const { results } = await this.client.search({
requests: [
{ indexName: INDICES.products, query, hitsPerPage: 5 },
{ indexName: INDICES.articles, query, hitsPerPage: 3 },
{ indexName: INDICES.faq, query, hitsPerPage: 3 },
],
});
return results;
}
}
| Issue | Cause | Solution |
|---|---|---|
| Circular dependency | Service imports client imports service | Use lazy initialization |
| Config drift | Dashboard edits not in code | Apply settings from code in CI |
| Transform errors | DB schema change | Add validation in transformer |
| Index name typo | Hardcoded strings | Use INDICES constants |
For multi-environment setup, see algolia-multi-env-setup.