Quick Atomic Search Starter using Next.JS

I recently updated my personal blog website from ASP.NET Core to Next.JS as the underlying development platform. In this journey I also wanted to be able to test out using the Atomic Coveo search user interface. This post will highlight some of the key aspects of building my search page using Coveo.

The End Goal

The goal of this post is to share details so that you could create your own Next.JS Coveo Atomic search interface like my website search: https://www.marnochastudios.com/search

Indexing the Content

My first step was to prepare my website and content for indexing. I’m a big fan of the Sitemap connector and decided it would be my best solution for crawling content as it is fast, and I have control over what is indexed. To setup my sitemap, I followed this path:

1. You can build your own Next.JS sitemap following something like this: https://nextjs.org/learn/seo/crawling-and-indexing/xml-sitemaps
2. I found that was limiting and I’d have to write more code, but I came across a NPM package that helps with generating it for you as well as supports server side rendered pages. Here is a link to the package: https://nextjs.org/learn/seo/crawling-and-indexing/xml-sitemaps
3. I found this video helpful on the use of the package and working with a server side rendered page: https://www.youtube.com/watch?v=fOoH9Z5adrg

Here is my working configuration: https://gist.github.com/marnocha/1fc4bc409540779c0adf6500eb68c54b

After I had my sitemap setup at https://www.marnochastudios.com/sitemap.xml
that includes my static sitemap (generated at build time), and my dynamic
sitemap (generated at run time) – I can now add my website to Coveo Cloud using
the Sitemap connector. You can follow this documentation to add a source: https://docs.coveo.com/en/1967/index-content/add-or-edit-a-sitemap-source.

Creating an API Key

Next you want to create an API Key in Coveo so your page can interact with Coveo. Follow the documentation here: https://docs.coveo.com/en/105/build-a-search-ui/api-key-authentication.

You can test your API key by using your key and Organization ID in a basic html page or in a sandbox like this: https://codesandbox.io/s/github/coveooss/atomic-basic-page-tutorial/tree/lesson-1-02-facets/?from-embed

Add Coveo Atomic to your Project 

Since I’m using Next.JS which built on the React Framework,
I followed the install guide and sample code provided by Coveo. It boils down
to:

1. Running: npm install @coveo/atomic
2. Running: npm install @coveo/atomic-react
3. Adding this line to your _app.js or _app.tsx in your pages folder:
   • import '@coveo/atomic/dist/atomic/themes/coveo.css';
4. Create a search.tsx page in your pages folder leveraging this code as starter: https://github.com/coveo/ui-kit/blob/master/packages/samples/atomic-next/pages/index.tsx
5. Replace the accessToken and organizationId strings with your own.
6. Update your fieldsToInclude based on your needs. I’ll get into fields more in the next section.
7. Here is my search page code: https://gist.github.com/marnocha/2c144914d70361cd925b73d729a57029
8. Lastly you can add custom fonts/styling to get my look and feel. Here is my custom CSS related to my search interface: https://gist.github.com/marnocha/f0db90ba90744db9b0beae3b72c3a5d5

Fields and Field Mapping

For my search page to work, it is expecting that you have content and fields in Coveo that are used for the Facets. Metadata and Featured Images. See below for my fields I created in Coveo. 

You can crawl https://coveo.com/blog/sitemap.xml if you want to see results and do the proper field mapping. See this documentation for field mapping, or search on Coveo Level Up training for courses on field mapping. https://docs.coveo.com/en/1640/index-content/manage-source-mappings. See below image for an example of what my mappings look like.

Pro Tips

A couple of pro tips that I would share after building my search page:

1.  If your page metadata names/properties have a prefix like “coveo:featuredimage” when you add the mappings in Coveo you must add “:crawler” to the end to specify the origin value. Specifically from the documentation - https://docs.coveo.com/en/1839/index-content/mapping-rule-syntax-reference
   - “When your metadata includes a colon, you must be careful when formatting
   your rule because the keyword following the last colon is interpreted as the
   metadata origin. Therefore, if you want to keep the colon in your metadata
   name, you must include an origin in the placeholder to disambiguate the rule
   format.”
2. By default, the Sitemap connector doesn’t index the content of the meta tags in the head of web pages listed in your sitemap for performance reasons. You can add your metadata to your sitemap, or you can turn this feature on: https://docs.coveo.com/en/2656/index-content/index-xml-sitemap-metadata#meta-tags-of-listed-web-pages
3. If you want to see all the AI and Machine Learning features in action, you must configure them by creating the model and associating them to your pipeline. Reference: https://docs.coveo.com/en/1832/leverage-machine-learning/manage-machine-learning-models
4. Smart Snippets is one Machine Learning model that isn’t available in a trial/demo organization so you would have to reach out to Coveo to get that purchased or enabled. More documentation: https://docs.coveo.com/en/l6eb0531/leverage-machine-learning/about-smart-snippets