npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@aha-app/netlify-flexsearch

v0.1.9

Published

Implement search for static sites on Netlify, powered by FlexSearch and Netlify functions

Downloads

55

Readme

CircleCI

netlify-flexsearch

netlify-flexsearch provides a set of tools for implementing search for static sites hosted on Netlify, powered by FlexSearch and Netlify functions.

When do I need this?

You might find this library useful if:

  1. You are building a static site on Netlify and you would like to implement search.
  2. You need to index a large enough quantity of data that building an in-browser search index will cause performance problems.
  3. You don't want to add a third-party service such as Algolia.

How does it work?

Netlify functions are serverless functions that Netlify automatically detects in your build and serves as APIs. This library helps you generate one or more Netlify functions during your build process which each contain a FlexSearch index. You can then make asynchronous requests to these functions to perform searches; the package also includes helper functions for making search requests.

Installation

npm install flexsearch @aha-app/netlify-flexsearch

or

yarn add flexsearch @aha-app/netlify-flexsearch

Usage

  1. Create a build script which invokes createSearchIndex one or more times. createSearchIndex accepts one object argument with the following options:

| Name | Type | Description | | --- | --- | --- | | index (required) | string | Unique name for the search index (this determines its API path) | | data (required) | object | Search data to be indexed (see example below for the required format) | | functionsPath (required) | string | Directory where you have configured Netlify functions (relative to the root directory of your application) | | flexSearchOptions (optional) | object | Additional options to be passed to FlexSearch when creating the index (see the FlexSearch documentation for available options) |

const createSearchIndex = require('@aha-app/netlify-flexsearch/createSearchIndex');

// Data must take on this exact format: an object where each key
// is a unique ID and the value is an object containing `text`
// (the text to be indexed for search) and `response` (the data that
// should be returned when this record is found via search).
const blogPosts = {
  "hello-world": {
    text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque augue odio, accumsan eu turpis et, fermentum pellentesque justo.",
    response: {
      slug: "hello-world",
      title: "Hello World"
    }
  },
  "second-post": {
    text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque augue odio, accumsan eu turpis et, fermentum pellentesque justo.",
    response: {
      slug: "second-post",
      title: "Second Post"
    }
  }
}

createSearchIndex({
  index: 'blog',
  data: blogPosts,
  functionsPath: 'src/functions'
});
  1. You should add a .gitignore entry to prevent the output of this script from being checked into git. If your Netlify functions folder is src/functions, the .gitignore entry might be src/functions/search* (all output filenames will begin with search).

  2. Modify your Netlify build command to invoke the script defined in step 1 in addition to your regular build. For example, if your build command is currently gatsby build and you named the script from step createSearch.js, you might change the build command to node createSearch.js && gatsby build.

  3. Import and use one of the helper functions for searching. The package provides both a React hook and a basic asynchronous function.

// Search.js (React-based usage)
import { useSearch } from '@aha-app/netlify-flexsearch';

const Search = () => {
  // useSearch accepts two arguments:
  // 
  // The first (required) is the string name of the index to
  // search -- this must match the index name provided when
  // building the inddex
  // 
  // The second (optional) is an object of additional options:
  // - debounce (default 250)
  // - defaultSearchTerm (prefill the search with a term)
  // - limit (default 25; limit the number of results that are returned)
  // - excerpt (default none; will populate the response with the n words surrounding the first match, if possible)
  const [searchTerm, setSearchTerm, results, loading, error] = useSearch('blog', { debounce: 300 });

  return (
    <div>
      <input
        type="search"
        value={searchTerm}
        onChange={e => setSearchTerm(e.target.value)}
        placeholder="Search..."
      />

      <h1>Search results</h1>

      {loading && "Loading..."}
      {error && `Oh no! Something went wrong.`}
      {!(loading || error) && (
        <ul>
          {results.map((result) => (
            // Result data here matches what is provided in the
            // `response` object when building the index.
            <li key={result.id}>
              <strong>{result.name}</strong>
              <p>
                {result.excerpt.moreBefore && '...'}
                {result.excerpt.text}
                {result.excerpt.moreAfter && '...'}
              </p>
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}
// Non-React helper
import { search } from '@aha-app/netlify-flexsearch';

search({ index: 'blog', term: 'hello', limit: 10 }).then(response => {
  // Do something with the results
  console.log(response.results);
})

Caveats

  • By default, Netlify functions run with 1024MB of RAM, so if your search index is too large you will see a build error.
  • This library has also not been tested with search indexes larger than a few MB; you might see slow/unacceptable search performance if your search index is hundreds of MB, even if it's under the 1024MB limit.

License

MIT