Algolia Search Integration

Overview

This public intake copy packages

plugins/antigravity-awesome-skills/skills/algolia-search

https://github.com/sickn33/antigravity-awesome-skills

Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.

This intake keeps the copied upstream files intact and uses

metadata.json

ORIGIN.md

Algolia Search Integration Expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, and relevance tuning

Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Patterns, Sharp Edges, Validation Checks, Collaboration, Limitations.

When to Use This Skill

Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.

• 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

Operating Table

metadata.json

ORIGIN.md

SKILL.md

SKILL.md

## Related Skills

Workflow

This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.

1. Confirm the user goal, the scope of the imported workflow, and whether this skill is still the right router for the task.
2. Read the overview and provenance files before loading any copied upstream support files.
3. Load only the references, examples, prompts, or scripts that materially change the outcome for the current request.
4. Execute the upstream workflow while keeping provenance and source boundaries explicit in the working notes.
5. Validate the result against the upstream expectations and the evidence you can point to in the copied files.
6. Escalate or hand off to a related skill when the work moves out of this imported workflow's center of gravity.
7. Before merge or closure, record what was used, what changed, and what the reviewer still needs to verify.

Imported Workflow Notes

Imported: 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 ( <article> <h3>{hit.name}</h3> <p>{hit.description}</p> <span>${hit.price}</span> </article> ); }

export function ProductSearch() { return ( <InstantSearch searchClient={searchClient} indexName={INDEX_NAME}> <Configure hitsPerPage={20} /> <SearchBox placeholder="Search products..." classNames={{ root: 'relative', input: 'w-full px-4 py-2 border rounded', }} /> <Hits hitComponent={Hit} /> </InstantSearch> ); }

// Custom hook usage import { useSearchBox, useHits, useInstantSearch } from 'react-instantsearch';

function CustomSearch() { const { query, refine } = useSearchBox(); const { hits } = useHits<ProductHit>(); const { status } = useInstantSearch();

return ( <div> <input value={query} onChange={(e) => refine(e.target.value)} placeholder="Search..." /> {status === 'loading' && <p>Loading...</p>} <ul> {hits.map((hit) => ( <li key={hit.objectID}>{hit.name}</li> ))} </ul> </div> ); }

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

• https://www.algolia.com/doc/api-reference/widgets/react
• https://www.algolia.com/doc/libraries/javascript/v5/methods/search/

Next.js Server-Side Rendering

SSR integration for Next.js with react-instantsearch-nextjs package.

Use <InstantSearchNext> instead of <InstantSearch> 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, }, }} > <div className="flex gap-8"> <aside className="w-64"> <h3>Categories</h3> <RefinementList attribute="category" /> <h3>Brand</h3> <RefinementList attribute="brand" /> </aside> <main className="flex-1"> <SearchBox placeholder="Search products..." /> <Hits hitComponent={ProductHit} /> </main> </div> </InstantSearchNext> ); }

// 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 */} </InstantSearchNext>

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

• https://www.npmjs.com/package/react-instantsearch-nextjs
• https://www.algolia.com/developers/code-exchange/instantsearch-and-next-js-starter

Data Synchronization and Indexing

Indexing strategies for keeping Algolia in sync with your data.

Three main approaches:

1. Full Reindexing - Replace entire index (expensive)
2. Full Record Updates - Replace individual records
3. 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

• https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/in-depth/the-different-synchronization-strategies
• https://www.algolia.com/blog/engineering/search-indexing-best-practices-for-top-performance-with-code-samples

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}

// 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

• https://www.algolia.com/doc/guides/security/api-keys
• https://support.algolia.com/hc/en-us/articles/14339249272977-What-are-the-best-practices-to-manage-Algolia-API-keys-in-my-code-and-protect-them

Custom Ranking and Relevance Tuning

Configure searchable attributes and custom ranking for relevance.

Searchable attributes (order matters):

1. Most important fields first (title, name)
2. Secondary fields next (description, tags)
3. 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

• https://www.algolia.com/doc/guides/managing-results/relevance-overview
• https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking

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 ( <InstantSearch searchClient={searchClient} indexName={INDEX_NAME}> <div className="flex gap-8"> {/* Filters Sidebar */} <aside className="w-64 space-y-6"> <ClearRefinements /> <CurrentRefinements />

      {/* 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

• https://www.algolia.com/doc/guides/managing-results/refine-results/faceting
• https://www.algolia.com/doc/api-reference/widgets/refinement-list/react

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<HTMLDivElement>(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 <div ref={containerRef} />; }

// 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 ( <InstantSearch searchClient={searchClient} indexName="products"> <AlgoliaAutocomplete placeholder="Search products..." detachedMediaQuery="(max-width: 768px)" /> <Hits hitComponent={ProductHit} /> </InstantSearch> ); }

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

• https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete
• https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/how-to/optimizing-query-suggestions-relevance/js

Examples

Example 1: Ask for the upstream workflow directly

Use @algolia-search-v2 to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.

Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.

Example 2: Ask for a provenance-grounded review

Review @algolia-search-v2 against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.

Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.

Example 3: Narrow the copied support files before execution

Use @algolia-search-v2 for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.

Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.

Example 4: Build a reviewer packet

Review @algolia-search-v2 using the copied upstream files plus provenance, then summarize any gaps before merge.

Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.

Best Practices

Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.

• Keep the imported skill grounded in the upstream repository; do not invent steps that the source material cannot support.
• Prefer the smallest useful set of support files so the workflow stays auditable and fast to review.
• Keep provenance, source commit, and imported file paths visible in notes and PR descriptions.
• Point directly at the copied upstream files that justify the workflow instead of relying on generic review boilerplate.
• Treat generated examples as scaffolding; adapt them to the concrete task before execution.
• Route to a stronger native skill when architecture, debugging, design, or security concerns become dominant.

Troubleshooting

Problem: The operator skipped the imported context and answered too generically

Symptoms: The result ignores the upstream workflow in

plugins/antigravity-awesome-skills/skills/algolia-search

metadata.json

ORIGIN.md

Problem: The imported workflow feels incomplete during review

Symptoms: Reviewers can see the generated

SKILL.md

Problem: The task drifted into a different specialization

Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better. Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.

Related Skills

• @advogado-especialista-v2

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

• @aegisops-ai-v2

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

• @agent-evaluation-v2

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

• @agent-framework-azure-ai-py-v2

  - Use when the work is better handled by that native specialization after this imported skill establishes context.

Additional Resources

Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.

references

references/n/a

examples

examples/n/a

scripts

scripts/n/a

agents

agents/n/a

assets

assets/n/a

Imported Reference Notes

Imported: 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

Imported: 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).

Imported: 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)

Imported: Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.