Providing great search experiences to users is an effective way to increase page views, conversions, and user engagement. However, implementing good search functionality into your website takes time and effort. Luckily, Algolia allows you to easily integrate search features into your application. In this article, you will learn how to integrate Algolia InstantSearch into your Next.js application.
What Is Algolia InstantSearch?
As stated in Algolia's docs, InstantSearch.js is an open-source UI library for JavaScript that lets you effortlessly build a search interface in your front-end application. The goal behind behindInstantSearch is to help you implement great search experiences with no effort by providing you with a complete search ecosystem. In detail, InstantSearch comes with several front-end components that you can assemble into unique search interfaces.
Get Started with Algolia + Next.js
You can have a look at the full code of the Next.js demo app integrated with Algolia in the GitHub repository supporting the article. Clone it and launch the demo web application locally with the following commands:
Now, let’s learn how to achieve this result!
Before learning how to integrate Algolia InstantSearch into your app, let's set up a Next.js application.
For the sake of simplicity, you can use DatoCMS’s Next.js Blog starter project. But keep in mind that any other Next.js project will do.
Follow the instructions in the GitHub repository of the Next.js Blog starter project. Let’s call the project “Next.js Blog with Algolia InstantSearch” as below:
Choose Vercel as the hosting and deployment platform. Then, keep following the initialization process until you get the following window:
At this point, you should now be able to access your Vercel project. In this example, the demo application public URL provided by Vercel is:
https://next-js-blog-with-algolia-instantsearch-cyqm9r9er-tonel.vercel.app/
Now, launch the git clone command you can see in the confirmation window. This will download the project that has just been created automatically by the process. In this example, the command is:
git clone https://github.com/Tonel/next.js-blog-with-algolia-instantsearch
Then, configure your .env
file as explained in the GitHub repository of the Next.js Blog starter project. You can now launch your project locally with the following commands:
npm installnpm run dev
Visit http://localhost:3000
in your browser, and you should now be seeing the web page below:
You are ready to integrate Algolia InstantSearch! Let’s learn how!
Prerequisites
To make Algolia InstantSearch work, you need the following two libraries.
algoliasearch: A fast, complete, fully-featured JavaScript API client to interact with Algolia API.
react-instantsearch-dom: A library that allows you to build fast search UIs based on Algolia in React.
You can add both to your project’s dependencies with the command below:
npm install algoliasearch react-instantsearch-dom
Set Up Algolia
Follow this step-by-step tutorial and learn how to configure Algolia.
Sign up for Algolia
First, you need to create an Algolia account.
If you already have an Algolia account, you can skip this step.
Otherwise, you can sign up for Algolia here.
Follow the instructions until you land on the page below:
Define your Algolia index
Now, you need to create your first index. An Algolia index stores the data that you want to make searchable in Algolia. You can think of an Algolia index as a sort of NoSQL document that keeps JSON objects of your content. Learn more about indexing in Algolia.
Fill out the form you see on the page where you landed at the end of the sign-up process as below:
Algolia indexCall your index “my_blog_content,” and click “Create index.”
Retrieve your API Keys
You now have to retrieve your Algolia keys. You can find them in the Settings > API Keys page below:
Here, you can see your Algolia Application ID
, Search-Only
API Key, and Admin
API Key. Store them in the .env
file of your Next.js application as follows:
NEXT_PUBLIC_ALGOLIA_APPLICATION_ID=<YOUR_ALGOLIA_APPLICATION_ID>NEXT_PUBLIC_ALGOLIA_SEARCH_ONLY_API_KEY=<YOUR_ALGOLIA_SEARCH_ONLY_APY_KEY>ALGOLIA_ADMIN_KEY=<YOUR_ALGOLIA_ADMIN_KEY>
Application ID
and the Search-Only
API Key provide read-only access to your search results. In detail, you will use them when implementing InstantSearch in the frontend, and it is safe to expose them to the client. You can achieve this by prefacing these two environment variables with NEXT_PUBLIC_.
On the other hand, the Admin API Key must remain secret. This is because this key provides write access to your Algolia index. Therefore, it should be used exclusively on the server side.
Congrats! You just finished setting up Algolia! Let’s now start writing some code!
Programmatically Import Your Data to Algolia
Let’s learn how to create a Next.js API that fetches your data, converts it into a new format, and sends it to your Algolia index. This is necessary because you need to provide Algolia with some data if you want to take advantage of its search capabilities. To achieve this, you can use the Algolia API.
Build a Next.js API to upload your data to your Algolia index
First, let’s create a Next.js API to write your data to your Algolia target index. Keep in mind that any JavaScript file inside the pages/api
folder will be treated by Next.js as an API endpoint.
So, create algolia-sync.js
file in the pages/api
folder as follows:
1import { request } from '@/lib/datocms';2import algoliasearch from 'algoliasearch/lite';3
4export default async (req, res) => {5 // initializing the Algolia client with the secret keys6 if (req.method === 'POST') {7 // Process a POST request8
9 const algoliaClient = algoliasearch(10 process.env.NEXT_PUBLIC_ALGOLIA_APPLICATION_ID,11 process.env.ALGOLIA_ADMIN_KEY,12 );13
14 // setting the Algolia index related to your blog15 const index = algoliaClient.initIndex('my_blog_content');16
17 const pageSize = 20;18
19 // retrieving all posts from the headless CMS20 const allPostsGraphqlRequest = (first, skip) => {21 return {22 query: `23 {24 allPosts(orderBy: date_DESC, first: ${first}, skip: ${skip}) {25 id26 title27 slug28 excerpt29 date30 }31 meta: _allPostsMeta {32 count33 }34 }35 `,36 };37 };38
39 const postResponse = await request(allPostsGraphqlRequest(pageSize, 0));40 // the number of all posts available41 const postCount = postResponse.meta.count;42
43 // iterating over the posts because the allPosts query is paginated44 // by default45 for (let page = 0; page < Math.ceil(postCount / pageSize); page++) {46 const posts = await request(47 allPostsGraphqlRequest(pageSize, page * pageSize),48 );49
50 // converting tha data retrieved by the headless CMS51 // into the desired Algolia format52 const algoliaPosts = posts.allPosts.map((post) => {53 return {54 objectID: post.id,55 title: post.title,56 excerpt: post.excerpt,57 slug: post.slug,58 date: post.date,59 };60 });61
62 // saving the post info to Algolia63 await index.saveObjects(algoliaPosts);64 }65
66 res.json(`Content successfully synchronized with Algolia search`);67 res.end();68 }69};
As you can see, this API takes care of fetching all your blog post data from DatoCMS, one page at a time
Then, it converts the data into a format more convenient for Algolia, and uses the Algolia API to write it to your Algolia index. In detail, you have to convert your data because every Algolia object in an index requires a objectID
field. If you do not send an objectID
, you can ask Algolia to generate it for you.
Keep in mind that Algolia's saveObjects()
function redefines the entire set of an object’s attributes, except for its objectID
field. In other words, if an object is not present in the index based on its objectID
field, Algolia adds it. Otherwise, it fully replaces all its attributes. This means that when calling this API multiple times, you should not worry about producing duplicates on the Algolia index. Also, saveObjects()
automatically divides your records into batches of 1,000 elements behind the scene to provide good performance. So, you can pass as many objects as you want to the Algolia API.
You now need to deploy your application so that you can then publicly access the API you just defined. Keep in mind that in a real-world scenario, you should protect the API with an authorization system, such as Basic Access Authentication.
If you are following the current example and your GitHub repo is connected to Vercel, you first need to set up the environment variables on Vercel. To achieve this, visit the “Environment Variables” page of your “Project Settings” and define the same environment variables contained in the .env
file.
Then, you only have to perform a git push operation with the commands below:
git add .git commit -m "Algolia Sync API added"git push origin
At the end of the process, Vercel will automatically redeploy your application. So, you will be able to launch the API by hitting the /api/algolia-sync
path in your online app on Vercel. In this example, the complete path to call the API is:
https://next-js-blog-with-algolia-instantsearch-cyqm9r9er-tonel.vercel.app/api/algolia-sync
Call the API, wait for it to complete, and visit the Data Sources > Indices > my_log_content page in the Algolia platform. Here, you can verify if the blog data has been written correctly to the Algolia index. You should be seeing the following list:
Create a DatoCMS Webhook to call the API
DatoCMS allows you to create webhooks. A DatoCMS webhook sends an HTTP notification when data changes in one of your projects, based on how you defined it. For example, you can use a webhook to synchronize DatoCMS data with third-party systems, such as Algolia.
In this case, you can set up a DatoCMS webhook that calls the API defined above every time a new post is published. Visit the Settings > Webhooks
section of your DatoCMS admin area and create a webhook as follows:
Then, define the following trigger:
This way, the webhook will be triggered every time a blog post gets published. Click on “Submit” and your webhook should now be live!
Verify that the data synchronization process works
To verify that the webhook works, update the title of the “Mistakes Tourists Make on Their First Trip Abroad” post in the DatoCMS content management panel as below:
Click “Save,” then “Publish.” DatoCMS will perform an HTTP POST request towards the specified endpoint. The HTTP body will be in JSON format, and will contain all the information relevant to the event just happened.
Now, visit your Algolia index data page and you should see the new title, as follows:
Great! You just integrated Algolia with DatoCMS. As you can see, it took only a few minutes.
Integrate Algolia InstantSearch in the Next.js Frontend
Algolia InstantSearch provides you with some basic components, but these have a style and interaction that may not fit your Next.js application. Fortunately, you can build Algolia Search frontend functionality with custom search components. Let's see how!
Build custom search components on Next.js
First, let’s define a SearchBox
component as follows:
1import { connectSearchBox } from "react-instantsearch-dom"2
3function SearchBox({ refine }) {4 return (5 <input6 className="search-box"7 type="search"8 placeholder="Search..."9 onChange={(e) => refine(e.currentTarget.value)}10 />11 )12}13
14export default connectSearchBox(SearchBox)
This is the input component where the users can type the search text to provide Algolia with. In detail, the connectSearchBox()
function from react-instantsearch-dom
automatically connects the custom search box to the InstantSearch
client.
Then, you will need a SearchHits
component:
1import { connectStateResults } from 'react-instantsearch-dom';2import Link from 'next/link';3
4function SearchHits({ searchState, searchResults }) {5 // checking if the query length is >= 36 // (since 3 is the minimum Algolia query length)7 const validQuery = searchState.query?.length >= 3;8
9 return searchState.query && validQuery ? (10 <div className={'search-hits'}>11 {searchResults?.hits.length === 0 && <div>No results found!</div>}12
13 {searchResults?.hits.length > 0 &&14 searchResults.hits.map((hit) => (15 <div key={hit.objectID} className="text-2xl mb-3 leading-snug">16 <Link href={`/posts/${hit.slug}`}>17 <a className="hover:underline">{hit.title}</a>18 </Link>19 </div>20 ))}21 </div>22 ) : null;23}24
25export default connectStateResults(SearchHits);
This component displays the search results returned by Algolia. Specifically, the connectStateResults() function provides the custom component with the Algolia state and search hits. The hits are nothing more than the results returned by the Algolia API based on the search text provided by the user in the SearchBox
component.
Now, let’s build a Search component by using the two components above:
1import algoliasearch from "algoliasearch/lite";2import { InstantSearch } from "react-instantsearch-dom";3import SearchBox from "./search-box";4import SearchHits from "./search-hits";5
6const searchClient = algoliasearch(7 process.env.NEXT_PUBLIC_ALGOLIA_APPLICATION_ID,8 process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_ONLY_API_KEY,9);10
11export default function Search() {12 return (13 <div className={"algolia-search"}>14 <InstantSearch searchClient={searchClient} indexName="my_blog_content">15 <SearchBox />16 <SearchHits />17 </InstantSearch>18 </div>19 );20}
This is based on the Algolia InstantSearch
component, which requires a searchClient
and an indexName
. The first is an instance of the Algolia API client you can create with the algoliasearch
library, while the second is the name of your Algolia target index.
Add the Search component to your homepage
Now, update your index.js
file to use the Search component defined earlier. All you have to do is import Seach and place it inside the Container component, as follows:
1// omitted for brevity ...2import Search from '@/components/search';3
4export default function Index({ subscription }) {5 // omitted for brevity ...6
7 return (8 <>9 <Layout preview={subscription.preview}>10 <Head>{renderMetaTags(metaTags)}</Head>11 <Container>12 <Search />13 <Intro />14 {heroPost && (15 <HeroPost16 title={heroPost.title}17 coverImage={heroPost.coverImage}18 date={heroPost.date}19 author={heroPost.author}20 slug={heroPost.slug}21 excerpt={heroPost.excerpt}22 />23 )}24 {morePosts.length > 0 && <MoreStories posts={morePosts} />}25 </Container>26 </Layout>27 </>28 );29}30
31// omitted for brevity ...
Similarly, add the Search component to the posts/[slug].js
post page:
1// omitted for brevity ...2import Search from "@/components/search";3
4// omitted for brevity ...5export default function Post({ subscription, preview }) {6 // omitted for brevity ...7
8 return (9 <Layout preview={preview}>10 <Head>{renderMetaTags(metaTags)}</Head>11 <Container>12 <Header />13 <Search />14 <article>15 <PostHeader16 title={post.title}17 coverImage={post.coverImage}18 date={post.date}19 author={post.author}20 />21 <PostBody content={post.content} />22 </article>23 <SectionSeparator />24 {morePosts.length > 0 && <MoreStories posts={morePosts} />}25 </Container>26 </Layout>27 );28}
Now, all your blog web pages offer useful and effective search functionality!
Algolia Search in Action in Next.js
Visit http://localhost:3000
in your browser, and you should be seeing a search input on top of your blog’s homepage. Type at least three characters, and Algolia InstantSearch will provide you with the corresponding search results, as below:
Et voilà! You just learned how to integrate Algolia InstantSearch into a Next.js project!
Algolia Next.js - Conclusion
In this article, you learned what Algolia InstantSearch is, how to set up Algolia, and how to integrate it into a Next.js blog website based on a headless CMS. As seen, integrating Algolia with DatoCMS takes only a few minutes. This is just one of the many integrations you can achieve with a powerful composable tool like DatoCMS.
Thanks for reading! We hope that you found this article helpful. Feel free to reach out to us on Twitter with any questions, comments, or suggestions.