How to Add Lunr Search to Your Gatsby Website

The Jamstack architecture is gaining significant traction for website development. Have you explored Gatsby, Nuxt, or Gridsome? Their ease of use and pre-built features are often impressive. However, search functionality isn't always a built-in feature, presenting a challenge for content-rich sites. Can we implement robust search without server-side components?

Jamstack inherently lacks built-in search capabilities. This requires careful consideration and implementation. While options exist, such as Algolia's search-as-a-service (with limitations on free plans) or leveraging WordPress's search with WPGraphQL and Apollo Client, this article focuses on a client-side solution.

We'll build a search index and integrate search into a Gatsby site using Lunr.js, a lightweight JavaScript library offering extensible and customizable search without external server dependencies. We recently used it on tartanify.com to add a "Search by Tartan Name" feature, overcoming challenges related to persistent, real-time search. This article will detail those challenges and solutions.

Getting Started

For simplicity, we'll use the official Gatsby blog starter. This abstracts many aspects of static website creation. To follow along:

gatsby new gatsby-starter-blog https://github.com/gatsbyjs/gatsby-starter-blog
cd gatsby-starter-blog
gatsby develop

This creates a small blog with three posts, accessible at http://localhost:8000/. Inspecting http://localhost:8000/__graphql reveals the available data.

Implementing an Inverted Index with Lunr.js

Lunr employs a record-level inverted index. This maps each word on the site to its location (page paths). We determine which fields (title, content, description, etc.) provide indexing keywords.

For our blog, we'll index titles and content. Titles are straightforward, but content requires cleaning. Initially using rawMarkdownBody proved problematic due to markdown syntax. We'll use the html field and the striptags package to remove HTML tags. Refer to the Lunr documentation for details.

Here's the Lunr index creation and population snippet (used later in gatsby-node.js):

const index = lunr(function () {
  this.ref('slug')
  this.field('title')
  this.field('content')
  for (const doc of documents) {
    this.add(doc)
  }
})

documents is an array of objects, each with slug, title, and content:

{
  slug: '/post-slug/',
  title: 'Post Title',
  content: 'Post content with all HTML tags stripped out.'
}

We define a unique document key (slug) and two fields (title and content). All documents are added iteratively.

Creating the Index in gatsby-node.js

First, install necessary libraries:

yarn add lunr graphql-type-json striptags

Next, modify gatsby-node.js. This file executes during site build, allowing us to add index creation. We'll use the Gatsby API createResolvers to create a new root field, LunrIndex.

Gatsby's data store and query capabilities are exposed via GraphQL field resolvers. getAllNodes retrieves nodes of a specified type:

/* gatsby-node.js */
// ... (imports)

exports.createResolvers = ({ cache, createResolvers }) => {
  createResolvers({
    Query: {
      LunrIndex: {
        type: GraphQLJSONObject,
        resolve: (source, args, context, info) => {
          const blogNodes = context.nodeModel.getAllNodes({ type: `MarkdownRemark` });
          const type = info.schema.getType(`MarkdownRemark`);
          return createIndex(blogNodes, type, cache);
        },
      },
    },
  });
};

// ... (createIndex function)

The createIndex function utilizes the Lunr snippet:

/* gatsby-node.js */
// ... (imports)

const createIndex = async (blogNodes, type, cache) => {
  // ... (Implementation to fetch and process data, including caching)
};

(The complete createIndex function, including data fetching, processing, and caching, is omitted for brevity but is crucial for a functional implementation. The original response provides this detail.) This ensures the index is only rebuilt when necessary.

Adding the Search Form Component

Create a search form component (src/components/search-form.js):

// ... (search form component implementation)

(The complete component implementation is omitted for brevity but is detailed in the original response.) This component handles form submission and input changes, navigating to /search with the query parameter.

Creating the Search Results Page

Create a search results page (src/pages/search.js):

// ... (search results page implementation)

(The complete page implementation is omitted for brevity, but is detailed in the original response.) This page uses the LunrIndex data to display search results.

Persistent Search Widget (Tartanify.com Example)

The tartanify.com example demonstrates a persistent instant search widget. The index creation is similar to the blog example, but simpler:

// ... (index creation for tartanify.com)

(The complete implementation is omitted for brevity but is detailed in the original response.) The key difference is the instant search functionality triggered by input changes, not form submission. The useStaticQuery hook is used for data fetching.

Making the Widget Persistent

To maintain the search widget across page changes, we use Gatsby's wrapPageElement API:

// gatsby-browser.js
// ... (wrapPageElement implementation)

(The complete implementation is detailed in the original response.) This wraps the page content with the search widget, ensuring persistence.

Custom Search Query Enhancements

The original response details improvements to the search query using Lunr's query method to handle fuzzy matches, wildcards, and boolean logic for better search results. This section significantly enhances the search experience.

Conclusion

Implementing search functionality in Jamstack websites is achievable and can significantly improve user experience. While seemingly at odds with the stateless nature of Jamstack, client-side solutions like Lunr.js offer powerful and flexible alternatives. The careful consideration and implementation detailed in this article highlight the potential for creating a superior user experience through thoughtful design and development.

The above is the detailed content of How to Add Lunr Search to Your Gatsby Website. For more information, please follow other related articles on the PHP Chinese website!