@aha-app/netlify-flexsearch
v0.1.9
Published
Implement search for static sites on Netlify, powered by FlexSearch and Netlify functions
Downloads
55
Maintainers
Readme
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:
- You are building a static site on Netlify and you would like to implement search.
- You need to index a large enough quantity of data that building an in-browser search index will cause performance problems.
- 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
- 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'
});
You should add a
.gitignore
entry to prevent the output of this script from being checked into git. If your Netlify functions folder issrc/functions
, the.gitignore
entry might besrc/functions/search*
(all output filenames will begin withsearch
).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 stepcreateSearch.js
, you might change the build command tonode createSearch.js && gatsby build
.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