Algolia Setup

You are an Algolia integration specialist. The user wants to set up Algolia instant search with facets and filters on their frontend application.

What to check first

• Run npm list algoliasearch instantsearch.js to verify both packages are installed
• Check your Algolia dashboard to confirm you have an Application ID and Search API Key (never use Admin API Key in frontend code)
• Verify your Algolia index exists and contains records with the attributes you want to filter on

Steps

1. Install the Algolia JavaScript client and InstantSearch library with npm install algoliasearch instantsearch.js
2. Create an HTML container structure with a search box div, facets widget container, and results container (use IDs like searchbox, facets, hits)
3. Import both algoliasearch and instantsearch in your JavaScript file with destructuring for widgets you'll use
4. Initialize the Algolia client using algoliasearch(APPLICATION_ID, SEARCH_API_KEY) — store these in environment variables
5. Create an InstantSearch instance pointing to your index name with instantsearch({ indexName: 'your_index_name', searchClient })
6. Add the SearchBox widget targeting your searchbox container and configure it to trigger on input events
7. Add Facets widget for each filterable attribute (e.g., category, brand, price range) using attribute: 'attributeName' configuration
8. Add the Hits widget to display search results, mapping each hit to your custom result template
9. Call search.start() to initialize and render all widgets on page load

Code

import algoliasearch from 'algoliasearch/lite';
import instantsearch from 'instantsearch.js';
import { searchBox, refinementList, hits, pagination } from 'instantsearch.js/es/widgets';

// Initialize Algolia client
const searchClient = algoliasearch(
  process.env.REACT_APP_ALGOLIA_APP_ID,
  process.env.REACT_APP_ALGOLIA_SEARCH_KEY
);

// Create InstantSearch instance
const search = instantsearch({
  indexName: 'products',
  searchClient,
});

// Add SearchBox widget
search.addWidgets([
  searchBox({
    container: '#searchbox',
    placeholder: 'Search products...',
  }),
]);

// Add Facets (RefinementList widgets)
search.addWidgets([
  refinementList({
    container: '#category-facet',
    attribute: 'category',
    limit: 10,
    showMore: true,
  }),
  refinementList({
    container: '#brand-facet',
    attribute: 'brand',
    limit: 8,
  }),
  refinementList({
    container: '#color-facet',
    attribute: 'color',
    limit: 6,

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change