⚡ The Meilisearch plugin for Strapi

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

Add your Strapi collections into a Meilisearch instance. The plugin listens to modifications made on your collections and updates Meilisearch accordingly.

• 📖 Documentation
• 🔧 Installation
• 🎬 Getting Started
• 💡 Run the Playground
• 🤖 Compatibility with Meilisearch and Strapi
• ⚙️ Development Workflow and Contributing
• 🌎 Community support
• 🤩 Just for the pleasure of the eyes

To understand Meilisearch and how it works, see the Meilisearch's documentation.

To understand Strapi and how to create an app, see Strapi's documentation.

This package version works with the v3 of Strapi. If you are using Strapi v4, please refer to this README.

Inside your Strapi app, add the package:

With npm:

npm install strapi-plugin-meilisearch@strapi_v3

With yarn:

yarn add strapi-plugin-meilisearch@strapi_v3

To apply the plugin to Strapi, a re-build is needed:

strapi build

You will need both a running Strapi app and a running Meilisearch instance. For specific version compatibility see this section.

There are many easy ways to download and run a Meilisearch instance.

For example, if you use Docker:

docker pull getmeili/meilisearch:latest # Fetch the latest version of Meilisearch image from Docker Hub
docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --master-key=masterKey

If you don't have a running Strapi project yet, you can either launch the playground present in this project or create a Strapi project.

We recommend adding your collections in development mode to allow the server reloads needed to apply a listener to the collections.

strapi develop
// or
yarn develop

To run Meilisearch and Strapi on the same server you can use Docker. A Docker configuration example can be found in the directory resources/docker of this repository.

To run the Docker script add both files Dockerfile and docker-compose.yaml at the root of your Strapi project and run it with the following command: docker-compose up.

Now that you have installed the plugin, a running meiliSearch instance and, a running Strapi app, let's go to the plugin page on your admin dashboard.

On the left-navbar, Meilisearch appears under the PLUGINS category. If it does not, ensure that you have installed the plugin and re-build Strapi (see installation).

First, you need to configure credentials via the strapi config, or on the plugin page. The credentials are composed of:

• The host: The url to your running Meilisearch instance.
• The api_key: The master or private key as the plugin requires administration permission on Meilisearch.More about permissions here.

⚠️ The master or private key should never be used to search on your front end. For searching, use the public key available on the key route.

You can add you Meilisearch credentials in the upper box of the Meilisearch plugin page.

For example, using the credentials from the section above: Run Meilisearch, the following screen shows where the information should be.

Once completed, click on the add button.

To use the strapi config add the following to config/plugins.js or config/env/[NODE_ENV]/plugin.js:

module.exports = () => ({
  //...
  meilisearch: {
    // Your meili host
    host: "https://localhost:7700",
    // Your master key or private key
    apiKey: "masterKey",
  }
  //...
})

Using config/env/[NODE_ENV]/plugin.js, it is possible to have a config file for different environments.

Note that if you use both method, the config file overwrites the credentials added through the plugin page.

If you don't have any collection yet in your Strapi Plugin, please follow Strapi quickstart.

We will use, as example, the collections provided by Strapi's quickstart.

On your plugin homepage, you should have two collections appearing: restaurant and category.

By clicking on the left checkbox, the collection is automatically indexed in Meilisearch. For example, if you click on the restaurant checkbox, all your restaurants are now available in Meilisearch. We will see in start searching how to try it out.

Hooks are listeners that update Meilisearch each time you add/update/delete an entry in your collections. To activate them, you will have to reload the server. If you are in develop mode, click on the red Reload Server button. If not, reload the server manually!

By default, when indexing a collection in Meilisearch the index in Meilisearch has the same name as the collection. This behavior can be changed by setting the indexName property in the model file of the related collection.

Example:

In the following example, the model restaurant index in Meilisearch is called my_restaurant instead of the default restaurant.

// api/restaurant/models/restaurant.js
module.exports = {
  meilisearch: {
    indexName: "my_restaurant"
  }
}

Examples can be found this directory.

It is possible to bind multiple collections to the same index. They all have to share the same indexName.

For example if shoes and shirts should be bind to the same index, they should have the same indexName in their model setting:

// api/shoes/models/shoes.js
module.exports = {
  meilisearch: {
    indexName: "product"
  }
}

// api/shirts/models/shirts.js
module.exports = {
  meilisearch: {
    indexName: "product"
  }
}

Now, on each entry addition from both shoes and shirts the entry is added in the product index of Meilisearch.

Nonetheless, it is not possible to know how many entries from each collection is added to Meilisearch.

For example, given two collections:

• Shoes: with 300 entries and an indexName set to product
• Shirts: 200 entries and an indexName set to product

The index product has both the entries of shoes and shirts. If the index product has 350 documents in Meilisearch, it is not possible to know how many of them are from shoes or shirts.

By default, the plugin sent the data the way it is stored in your Strapi collection. It is possible to remove or transform fields before sending your entries to Meilisearch.

Create the alteration function transformEntry in your Collection's model. Before sending the data to Meilisearch, every entry passes through this function where the alteration is applied.

You can find a lot of examples in this directory.

Example

To remove all private fields and relations from entries before indexing them into Meilisearch, use sanitizeEntity in the transFormEntry function.

// api/restaurant/models/restaurant.js
const { sanitizeEntity } = require('strapi-utils')
module.exports = {
  meilisearch: {
    transformEntry({ entry, model }) {
      return sanitizeEntity(entry, { model })
    },
  },
}

Another example:

The restaurant collection has a relation with the category collection. Inside a restaurant entry the category field contains an array of each category in an object format: [{ name: "Brunch" ...}, { name: "Italian ... }].

To change that format to an array of category names, add a map function inside the transformEntry function.

// api/restaurant/models/restaurant.js
module.exports = {
  meilisearch: {
    transformEntry(entry, model) {
      return  {
        ...entry,
        categories: entry.categories.map(cat => cat.name)
      };
    },
  }
}

Resulting in categories being transformed like this in a restaurant entry.

  {
    "id": 2,
    "name": "Squared Pizza",
    "categories": [
      "Brunch",
      "Italian"
    ],
    // other fields
  }

By transforming the categories into an array of names, it is now compatible with the filtering feature in Meilisearch.

Each index in Meilisearch can be customized with specific settings. It is possible to add your Meilisearch settings configuration to the indexes you create using settings field in your model's config.

The settings are added when either: adding a collection to Meilisearch or when updating a collection in Meilisearch. The settings are not updated when documents are added through the listeners.

For example

module.exports = {
  meilisearch: {
    settings: {
      filterableAttributes: ['genres'],
      distinctAttribute: null,
      searchableAttributes: ['title', 'description', 'genres'],
      synonyms: {
        wolverine: ['xmen', 'logan'],
        logan: ['wolverine', 'xmen']
      }
    }
  },
}

See resources for more settings examples.

Once you have a collection containing documents indexed in Meilisearch, you can start searching.

To search in Meilisearch, you can use the instant-meilisearch library that integrates a whole search interface, or our meilisearch-js SDK.

You can have a front up and running in record time with instant-meilisearch.

In Instant Meilisearch, you only have to provide your credentials and index name (uid). restaurant is the index name in our example.

You can have a quick preview with the following code in an HTML file. Create an HTML file, copy-paste the code below and open the file in your browser (or find it in /front_examples/restaurant.html).

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@meilisearch/instant-meilisearch/templates/basic_search.css" />
  </head>
  <body>
    <div class="wrapper">
      <div id="searchbox" focus></div>
      <div id="hits"></div>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/@meilisearch/instant-meilisearch/dist/instant-meilisearch.umd.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/instantsearch.js@4"></script>
    <script>
        const search = instantsearch({
            indexName: "restaurant",
            searchClient: instantMeiliSearch(
                "https://localhost:7700",
                'publicKey', // Use the public key not the private or master key to search.
            )
            });
            search.addWidgets([
              instantsearch.widgets.searchBox({
                  container: "#searchbox"
              }),
              instantsearch.widgets.configure({ hitsPerPage: 8 }),
              instantsearch.widgets.hits({
                  container: "#hits",
                  templates: {
                  item: `
                      <div>
                      <div class="hit-name">
                          {{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}
                      </div>
                      </div>
                  `
                  }
              })
            ]);
            search.start();
    </script>
  </body>
</html>

You can also use meilisearch-js to communicate with Meilisearch.

The following code is a setup that will output a restaurant after a search.

import { MeiliSearch } from 'meilisearch'
;(async () => {
  const client = new MeiliSearch({
    host: 'https://127.0.0.1:7700',
    apiKey: 'publicKey', // Use the public key not the private or master key to search.
  })
  // An index is where the documents are stored.
  const response = client.index('movies').search('Biscoutte')
})()

response content:

{
  "hits": [
    {
      "id": 3,
      "name": "Biscotte Restaurant",
      "description": "Welcome to Biscotte restaurant! Restaurant Biscotte offers a cuisine based on fresh, quality products, often local, organic when possible, and always produced by passionate producers.",
      "categories": []
    }
  ],
  "offset": 0,
  "limit": 20,
  "nbHits": 1,
  "exhaustiveNbHits": false,
  "processingTimeMs": 1,
  "query": "biscoutte"
}

Instead of adding the plugin to an existing project, you can try it out using the playground in this project.

# Root of repository
yarn playground:dev

This command will install the required dependencies and launch the app in development mode. You should be able to reach it on the port 8000 of your localhost.

Supported Strapi versions:

Complete installation requirements are the same as for Strapi itself and can be found in the documentation under installation Requirements.

• Strapi >=v3.6.x <v4.x.x

(This plugin may work with the older Strapi versions, but these are not tested nor officially supported at this time.)

Supported Meilisearch versions:

This package only guarantees the compatibility with the version v0.26.0 of Meilisearch.

Node / NPM versions:

• NodeJS >= 12.10 <= 14
• NPM >= 6.x

We recommend always using the latest version of Strapi to start your new projects.

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!

• For general help using Meilisearch, please refer to the official Meilisearch documentation.
• Contact the Meilisearch support
• Strapi community Slack
• For general help using Strapi, please refer to the official Strapi documentation.

Using the foodadvisor restaurant demo Strapi provided. We added a searchbar to it using instant-meilisearch.