Skip to content

Latest commit

 

History

History
276 lines (205 loc) · 12.8 KB

README.md

File metadata and controls

276 lines (205 loc) · 12.8 KB

Instant-Meilisearch

Autocomplete Meilisearch Client

Meilisearch | Meilisearch Cloud | Documentation | Discord | Roadmap | Website | FAQ

npm version Tests License Bors enabled

Meilisearch is an open-source search engine. Discover what Meilisearch is!

This library is the search client that you should use to make Meilisearch work with autocomplete. Autocomplete, an open-source project developed by Algolia, is a library that lets you quickly build an autocomplete experience.

Since autocomplete.js provides the possibility to use a custom data source, we are able to plug into it. Nonetheless, it has been created by Algolia and thus some of its components only works with Algolia.

Table of Contents

📖 Documentation

For general information on how to use Meilisearch—such as our API reference, tutorials, guides, and in-depth articles—refer to our main documentation website.

For information on how to use the autocomplete library refer to its documentation. It provides all the necessary information to set up your autocomplete experience.

⚡ Supercharge your Meilisearch experience

Say goodbye to server deployment and manual updates with Meilisearch Cloud. No credit card required.

🔧 Installation

Use npm or yarn to install the autocomplete client for Meilisearch.

yarn add @meilisearch/autocomplete-client
# or
npm install @meilisearch/autocomplete-client

@meilisearch/autocomplete-client is a client for autocomplete. It does not import the library.
To be able to use both, you need to install autocomplete as well.

🎬 Usage

The Meilisearch Autocomplete client provides 2 methods:

  • meilisearchAutocompleteClient({ host, url, options? }): The search client.
    • url: The URL to your Meilisearch instance.
    • apiKey: A valid API key with enough rights to search. ⚠️ Avoid using the admin key or master key
    • options: Additional options. See this section
  • getMeilisearchResults(searchClient, queries): The data source handler.
    • searchClient: The client created with meilisearchAutocompleteClient
    • queries: An array of queries. See this documentation on what queries accepts.

🎬 Getting started

To make autocomplete work with Meilisearch, create the autocompleteSearchClient and provide it to the getMeilisearchResults method as the searchClient. The following code provides a basic working code example.

import { autocomplete } from '@algolia/autocomplete-js'
import {
  meilisearchAutocompleteClient,
  getMeilisearchResults,
} from '@meilisearch/autocomplete-client'
import '@algolia/autocomplete-theme-classic'

const searchClient = meilisearchAutocompleteClient({
  url: 'https://ms-adf78ae33284-106.lon.meilisearch.io', // Host
  apiKey: 'a63da4928426f12639e19d62886f621130f3fa9ff3c7534c5d179f0f51c4f303'  // API key
})

autocomplete({
  container: '#autocomplete',
  placeholder: 'Search for games',
  getSources({ query }) {
    return [
      {
        sourceId: 'steam-video-games',
        getItems() {
          return getMeilisearchResults({
            searchClient,
            queries: [
              {
                indexName: 'steam-video-games',
                query,
              },
            ],
          })
        },
        templates: {
          item({ item, components, html }) {
            return html`<div>
              <div>${item.name}</div>
            </div>`
          },
        },
      },
    ]
  },
})

💅 Customization

The options field in the meilisearchAutocompleteClient function provides the possibility to alter the default behavior of the search.

const client = meilisearchAutocompleteClient({
  url: 'http://localhost:7700',
  apiKey: 'searchKey',
  options: {
    // other options
    meiliSearchParams: {
    },
  },
})

Placeholder Search

Placeholders search means showing results even when the search query is empty. By default it is true. When placeholder search is set to false, no results appears when the search box is empty.

{ placeholderSearch : true } // default true

Primary key

Specify the field in your documents containing the unique identifier (undefined by default). By adding this option, we avoid errors that are thrown in some environments. For example, In React particularly, this option removes the Each child in a list should have a unique "key" prop error.

{ primaryKey : 'id' } // default: undefined

Keep zero facets

keepZeroFacets set to true keeps the facets even when they have 0 matching documents (default false).

If in your autocomplete implementation you are showing the facet values distribution, same values may completely disapear when they have no matching documents in the current filtering state.

By setting this option to true, the facet values do not disapear and instead are given the distribution 0.

With keepZeroFacets set to true:

genres:

  • horror (2000)
  • thriller (214)
  • comedy (0)

With keepZeroFacets set to false, comedy disapears:

genres:

  • horror (2000)
  • thriller (214)
{ keepZeroFacets : true } // default: false

Request Config

You can provide a custom request configuration. Available field can be found here.

For example, with custom headers:

{
  requestConfig: {
    headers: {
      Authorization: AUTH_TOKEN
    },
    credentials: 'include'
  }
}

Custom HTTP client

You can use your own HTTP client, for example, with axios.

{
  httpClient: async (url, opts) => {
    const response = await $axios.request({
      url,
      data: opts?.body,
      headers: opts?.headers,
      method: (opts?.method?.toLocaleUpperCase() as Method) ?? 'GET'
    })
    return response.data
  }
}

Meilisearch search parameters

meiliSearchParams lets you override the parameters sent to Meilisearch. The following options can be overridden:

🤖 Compatibility with Meilisearch and Autocomplete

Supported autocomplete versions:

This package only guarantees the compatibility with the version v1.x.x of Autocomplete. It may work with older or newer versions, but these are not tested nor officially supported at this time.

API compatibility with autocomplete Some autocomplete parameters are not working using the meilisearch autocomplete client.

Supported Meilisearch versions:

This package guarantees compatibility with version v1.x of Meilisearch, but some features may not be present. Please check the issues for more info.

Node / NPM versions:

  • NodeJS >= 18

⚙️ Development Workflow and Contributing

Any new contribution is more than welcome in this project!

If you want to know more about the development workflow or want to contribute, please visit our contributing guidelines for detailed instructions!

Meilisearch provides and maintains many SDKs and Integration tools like this one. We want to provide everyone with an amazing search experience for any kind of project. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the integration-guides repository.