Integrating Algolia DocSearch with Astro.build

Teodora Udrea

Thursday 11 January 2024

How can you take your developer documentation website to the next level with a site-wide search functionality that’s both effective and cost-efficient?

Congratulations on choosing Astro.build  – a framework that blends modern web development practices with ease of use.

But how can you take your developer documentation website to the next level with a site-wide search functionality that’s both effective and cost-efficient?

Enter Algolia DocSearch, your solution for an enhanced search experience. This comprehensive guide will lead you through every step of integrating Algolia DocSearch v3 with your Astro.build (4.0 and higher) project.

Why Algolia DocSearch should be your go-to search solution

1. It’s free: a perfect match for open-source projects, Algolia DocSearch offers robust search capabilities at no additional cost.
2. Widely adopted: major tech projects like Bootstrap, Material UI, and Babel rely on Algolia DocSearch. This widespread adoption is a testament to its reliability and superior search functionality.
3. Rich feature set: Algolia DocSearch comes packed with features such as the Analytics API, Search Analytics, Crawler UI, and Natural Language Processing (NLP). These tools not only enhance user search experience but also offer valuable insights through back-end analytics.

Getting started with Algolia DocSearch

To kick things off, apply for Algolia DocSearch. Once you’re approved, you’ll receive an API key essential for integrating the search function into your Astro.build project.

Integrating Algolia DocSearch with Astro.build: a step-by-step guide

1. Add dependencies:

   • Install the necessary Algolia DocSearch packages:

     npm install @docsearch/react@3

2. Enable React integration:

   • Update your astro.config.mjs file to incorporate React:

     import { defineConfig } from "astro/config";
     import react from "@astrojs/react";
     
     export default defineConfig({
         integrations: [react()],
     });

3. Create a client-side React component:

   • Given Astro.build’s static precompilation, a client-side component ensures dynamic functionality. Here is what the DocSearchReact.jsx file could look like:

     import React, { useEffect } from 'react';
     import docsearch from '@docsearch/js';
     import '@docsearch/css';
     
     function DocSearchReact() {
       useEffect(() => {
         docsearch({
           container: '#docsearch',
           appId: 'YOUR_APP_ID',
           indexName: 'YOUR_INDEX_NAME',
           apiKey: '#YOUR_API_KEY',
         });
       }, []);
     
       return (
         <div id="docsearch"></div>
       );
     }
     
     export default DocSearchReact;

4. Implementing in Header.astro:

   • Embed the search component in the header for universal access:

     ---
     import { SITE } from '../../config';
     import DocSearchReact from './DocSearchReact';
     
     const { currentPage } = Astro.props;
     ---
     
     <header class="...">
         <nav title="Top Navigation" class="...">
             <div class="">
             </div>
     
             <!-- Algolia Docsearch component (Header/DocSearchReact) -->
             <DocSearchReact client:only="react"/>
     
             <div class="...">
             </div>
         </nav>
     </header>
     
     

• Note: Adding client:only="react"  is key for enabling the dynamic client-side interaction of the DocSearchReact component with the .astro file.

Wrapping up

Integrating Algolia DocSearch into your Astro.build project is a game-changer. It not only enhances the user experience but also makes your documentation more accessible and user-friendly. Follow this guide and you’ll have a powerful, efficient search tool seamlessly woven into your site.

Additional Resources

• Dive deeper into Algolia DocSearch features: Algolia DocSearch Features
• Explore more about Astro.build: Astro Documentation