How to add InstantSearch to a site with an unsupported framework (like Jekyll)

Oct 16th 2023engineering

Jekyll is an open-source static site generator originally developed by Tom Preston-Werner (the creator of GitHub) as a response to the bloated systems of the day like WordPress. Despite largely kicking off the static/Jamstack movement though, the developer world seems to have largely moved off of it. In 2021, the last active maintainer of the project and our friend Frank Taillandier passed away, leaving the project essentially unshepherded.

Nevertheless, many companies are still using Jekyll for their ecommerce projects because of the investment required to switch. After all, if you’ve got a team of Ruby developers and a perfectly-running website already, why fix what isn’t broken just to be more “modern”?

It’s a valid argument in some cases, so we wanted to update this old article to reflect how you can use Algolia with Jekyll (or any other custom, outdated, or otherwise unsupported framework for that matter) in 2023.

If you’d like to give this a go on a prototype Jekyll site before messing with your own integration, maybe check out Tom Preston-Werner’s blog, a complete Jekyll project that’s free to use with attribution as long as you don’t republish any of his articles.

Because it’s only possible to demonstrate search when you’ve got searchable data indexed, we’re not going to provide a code repository or free index to use so as to respect the licensing of Tom’s content. But this will work with any site on any framework, so give this a shot with your sample project of choice.

It works like this:

• • Build your index. How would it make the most sense to get the data you want to be searchable into Algolia? For the Jekyll blog we mentioned earlier, it’d probably make sense to write some step into the deployment process that scrapes the folder of blog posts, generates a JSON file that contains all the searchable data, and uploads it into Algolia via the API. Take a look at this docs article for a more extensive guide on this.

• • Choose which InstantSearch implementation you want to use. The most logical for Jekyll users would be the JS flavor, but some of the others might be helpful in certain situations. A Gatsby site is going to be better served by the React flavor, and an Astro site could make use of a few of them.

• • Write out your HTML. This part is straightforward: just block out the layout like you’re used to and you’ll be good. Take a look at the widget showcase here; once you pick out what widgets you’d like to use, create a container element for each one.

• • Import the InstantSearch library into your JavaScript on the frontend and create the search object with whatever templating system your framework includes piping in your Algolia credentials:

    const searchClient = algoliasearch('YourApplicationID', 
    'YourSearchOnlyAPIKey');
    const search = instantsearch({
          indexName: 'demo_ecommerce',
          searchClient
    });

• • Register the widgets you want with the HTML containers you just set up.

    search.addWidgets([
          searchBox({
                container: "#searchbox"
          }),
          hits({
                container: "#hits"
          })
    ]);
    search.start();

• • Make it look pretty! InstantSearch gives you something good-looking right out of the box, but it gives you the flexibility to make things nicer with CSS.

• • For bonus points, can you work this into the makeup of your chosen framework? In those I’m used to working with, I’d get more mileage out of this approach by encapsulating my search implementation in a component or two, isolating the CSS and JavaScript from the markup so it’s easier to maintain.

And that’s it! We get a lot of questions about using Algolia on unsupported frameworks, but after following these seven steps, you’ve got yourself a search engine on your site regardless of the framework you’re using.

It’s much more flexible than the old way of having a plugin for each little framework. Plus, all of the developers using obscure frameworks and custom implementations can help each other find solutions now that they’re going about it the same way.

So if you’ve got any questions about adding search to your site, feel free to check out Stack Overflow, our Discourse forum, and if you need more personal help, you can get a hold of us here.

Happy building!