Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

meilisearch

meilisearch481.5kMIT0.51.0TypeScript support: included

The Meilisearch JS client for Node.js and the browser.

meilisearch, search, instant, relevant, client, wrapper, meili

readme

Meilisearch-JavaScript

Meilisearch JavaScript

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

npm version Tests Codecov Prettier License Merge Queues enabled

⚡ The Meilisearch API client written for JavaScript

Meilisearch JavaScript is the Meilisearch API client for JavaScript developers.

Meilisearch is an open-source search engine. Learn more about Meilisearch.

Table of Contents

📖 Documentation

Consult the Meilisearch Documentation for guides, tutorials, and API reference materials on using Meilisearch.

For detailed information about the meilisearch-js package, visit the client library documentation.

🔧 Installation

This package is published to npm.

Installing with npm:

npm i meilisearch

[!NOTE]

Node.js LTS and Maintenance versions are supported and tested. Other versions may or may not work.

Other runtimes, like Deno and Bun, aren't tested, but if they do not work with this package, please open an issue.

Run Meilisearch

⚡️ Launch, scale, and streamline in minutes with Meilisearch Cloud—no maintenance, no commitment, cancel anytime. Try it free now.

🪨 Prefer to self-host? Download and deploy our fast, open-source search engine on your own infrastructure.

Import

After installing meilisearch-js, you must import it into your application. There are many ways of doing that depending on your development environment.

<summary>

⚠️ If any issues arise importing meilisearch/token

</summary>

[!WARNING]

  • default export is deprecated and will be removed in a future version | Issue
  • regarding usage of package's UMD version via script src, exports will stop being directly available on the global object | Issue

import syntax

Usage in an ES module environment:

import { Meilisearch } from "meilisearch";

const client = new Meilisearch({
  host: "http://127.0.0.1:7700",
  apiKey: "masterKey",
});

<script> tag

This package also contains a UMD bundled version, which in this case is meant to be used in a script src tag:

<script src="https://www.unpkg.com/meilisearch/dist/umd/index.min.js"></script>
<script>
    const client = new meilisearch.Meilisearch(/* ... */);
    // ...
</script>

But keep in mind that each CDN (JSDELIVR, ESM.SH, etc.) provide more ways to import packages, make sure to read their documentation.

require syntax

Usage in a back-end node.js or another environment supporting CommonJS modules:

const { Meilisearch } = require("meilisearch");

const client = new Meilisearch({
  host: "http://127.0.0.1:7700",
  apiKey: "masterKey",
});

React Native

To use meilisearch-js with React Native, you must also install react-native-url-polyfill.

Deno

Usage in a Deno environment:

import { Meilisearch } from "npm:meilisearch";

const client = new Meilisearch({
  host: "http://127.0.0.1:7700",
  apiKey: "masterKey",
});

🚀 Getting started

Take a look at the playground for a concrete example.

Add documents 

const { Meilisearch } = require('meilisearch')
// Or if you are in a ES environment
import { Meilisearch } from 'meilisearch'

;(async () => {
  const client = new Meilisearch({
    host: 'http://127.0.0.1:7700',
    apiKey: 'masterKey',
  })

  // An index is where the documents are stored.
  const index = client.index('movies')

  const documents = [
      { id: 1, title: 'Carol', genres: ['Romance', 'Drama'] },
      { id: 2, title: 'Wonder Woman', genres: ['Action', 'Adventure'] },
      { id: 3, title: 'Life of Pi', genres: ['Adventure', 'Drama'] },
      { id: 4, title: 'Mad Max: Fury Road', genres: ['Adventure', 'Science Fiction'] },
      { id: 5, title: 'Moana', genres: ['Fantasy', 'Action']},
      { id: 6, title: 'Philadelphia', genres: ['Drama'] },
  ]

  // If the index 'movies' does not exist, Meilisearch creates it when you first add the documents.
  let response = await index.addDocuments(documents)

  console.log(response) // => { "uid": 0 }
})()

Tasks such as document addition always return a unique identifier. You can use this identifier taskUid to check the status (enqueued, canceled, processing, succeeded or failed) of a task.

Basic search 

// Meilisearch is typo-tolerant:
const search = await index.search('philoudelphia')
console.log(search)

Output:

{
  "hits": [
    {
      "id": "6",
      "title": "Philadelphia",
      "genres": ["Drama"]
    }
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 1,
  "processingTimeMs": 1,
  "query": "philoudelphia"
}

Using search parameters

meilisearch-js supports all search parameters described in our main documentation website.

await index.search(
  'wonder',
  {
    attributesToHighlight: ['*']
  }
)
{
  "hits": [
    {
      "id": 2,
      "title": "Wonder Woman",
      "genres": ["Action", "Adventure"],
      "_formatted": {
        "id": "2",
        "title": "<em>Wonder</em> Woman",
        "genres": ["Action", "Adventure"]
      }
    }
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 1,
  "processingTimeMs": 0,
  "query": "wonder"
}

Custom search with filters

To enable filtering, you must first add your attributes to the filterableAttributes index setting.

await index.updateFilterableAttributes([
    'id',
    'genres'
  ])

You only need to perform this operation once per index.

Note that Meilisearch rebuilds your index whenever you update filterableAttributes. Depending on the size of your dataset, this might take considerable time. You can track the process using the tasks API).

After you configured filterableAttributes, you can use the filter search parameter to refine your search:

await index.search(
  'wonder',
  {
    filter: ['id > 1 AND genres = Action']
  }
)
{
  "hits": [
    {
      "id": 2,
      "title": "Wonder Woman",
      "genres": ["Action","Adventure"]
    }
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 1,
  "processingTimeMs": 0,
  "query": "wonder"
}

Placeholder search

Placeholder search makes it possible to receive hits based on your parameters without having any query (q). For example, in a movies database you can run an empty query to receive all results filtered by genre.

await index.search(
  '',
  {
    filter: ['genres = fantasy'],
    facets: ['genres']
  }
)
{
  "hits": [
    {
      "id": 2,
      "title": "Wonder Woman",
      "genres": ["Action","Adventure"]
    },
    {
      "id": 5,
      "title": "Moana",
      "genres": ["Fantasy","Action"]
    }
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 2,
  "processingTimeMs": 0,
  "query": "",
  "facetDistribution": {
    "genres": {
      "Action": 2,
      "Fantasy": 1,
      "Adventure": 1
    }
  }
}

Note that to enable faceted search on your dataset you need to add genres to the filterableAttributes index setting. For more information on filtering and faceting, consult our documentation settings.

Abortable search

You can abort a pending search request by providing an AbortSignal to the request.

const controller = new AbortController()

index
  .search('wonder', {}, {
    signal: controller.signal,
  })
  .then((response) => {
    /** ... */
  })
  .catch((e) => {
    /** Catch AbortError here. */
  })

controller.abort()

Using Meilisearch behind a proxy

Custom request config

You can provide a custom request configuration. for example, with custom headers.

const client: Meilisearch = new Meilisearch({
  host: 'http://localhost:3000/api/meilisearch/proxy',
  requestConfig: {
    headers: {
      Authorization: AUTH_TOKEN
    },
    // OR
    credentials: 'include'
  }
})

Custom http client

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

const client: Meilisearch = new Meilisearch({
  host: 'http://localhost:3000/api/meilisearch/proxy',
  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
  }
})

🤖 Compatibility with Meilisearch

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

💡 Learn more

The following sections in our main documentation website may interest you:

Check out the playgrounds for examples of implementation.

⚙️ Contributing

We welcome all contributions, big and small! If you want to know more about this SDK's development workflow or want to contribute to the repo, 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. For a full overview of everything we create and maintain, take a look at the integration-guides repository.