strapi-plugin-meilisearch

<p align="center"> <img src="https://raw.githubusercontent.com/meilisearch/integration-guides/main/assets/logos/meilisearch_strapi.svg" alt="Meilisearch-Strapi" width="200" height="200" /> </p> <h1 align="center">Meilisearch Strapi Plugin</h1> <h4 align="center"> <a href="https://github.com/meilisearch/meilisearch">Meilisearch</a> | <a href="https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=strapi-plugin-meilisearch">Meilisearch Cloud</a> | <a href="https://www.meilisearch.com/docs">Documentation</a> | <a href="https://discord.meilisearch.com">Discord</a> | <a href="https://roadmap.meilisearch.com/tabs/1-under-consideration">Roadmap</a> | <a href="https://www.meilisearch.com">Website</a> | <a href="https://www.meilisearch.com/docs/faq">FAQ</a> </h4> <p align="center"> <a href="https://www.npmjs.com/package/strapi-plugin-meilisearch"><img src="https://img.shields.io/npm/v/strapi-plugin-meilisearch.svg" alt="npm version"></a> <a href="https://github.com/meilisearch/strapi-plugin-meilisearch/actions"><img src="https://github.com/meilisearch/strapi-plugin-meilisearch/workflows/Tests/badge.svg" alt="Tests"></a> <a href="https://github.com/prettier/prettier"><img src="https://img.shields.io/badge/styled_with-prettier-ff69b4.svg" alt="Prettier"></a> <a href="https://github.com/meilisearch/strapi-plugin-meilisearch/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-informational" alt="License"></a> <a href="https://ms-bors.herokuapp.com/repositories/7"><img src="https://bors.tech/images/badge_small.svg" alt="Bors enabled"></a> </p> <p align="center">⚡ The Meilisearch plugin for Strapi</p>

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

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

Table of Contents

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

📖 Documentation

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.

⚡ Supercharge your Meilisearch experience

Say goodbye to server deployment and manual updates with Meilisearch Cloud. Get started with a 14-day free trial! No credit card required.

🔧 Installation

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

Inside your Strapi app, add the package:

With npm:

npm install strapi-plugin-meilisearch

With yarn:

yarn add strapi-plugin-meilisearch

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.

🏃‍♀️ Run Meilisearch

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

🏃‍♂️ Run Strapi

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 indexing your content-types to Meilisearch in development mode to allow the server reloads needed to apply or remove listeners.

strapi develop
// or
yarn develop

Run Both with Docker

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.

🎬 Getting Started

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).

🤫 Add Credentials

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.

Using the plugin page

You can add your Meilisearch credentials in the settings tab on 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.

Using a config file

To use the Strapi config add the following to config/plugins.js:

// config/plugins.js

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

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

🚛 Add your content-types to Meilisearch

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

We will use, as example, the content-types provided by Strapi's quickstart (plus the user content-type).

On your plugin homepage, you should have two content-types appearing: restaurant, category and user.

By clicking on the left checkbox, the content-type is automatically indexed in Meilisearch. For example, if you click on the restaurant checkbox, the indexing to Meilisearch starts.

Once the indexing is done, your restaurants are in Meilisearch. We will see in start searching how to try it out.

🪝 Apply Hooks

Hooks are listeners that update Meilisearch each time you add/update/delete an entry in your content-types. They are activated as soon as you add a content-type to Meilisearch. For example by clicking on the checkbox of restaurant.

Nonetheless, if you remove a content-type from Meilisearch by unchecking the checkbox, you need to reload the server. If you don't, actions are still listened to and applied to Meilisearch. The reload is only possible in develop mode; click on the Reload Server button. If not, reload the server manually!

💅 Customization

It is possible to add settings for every collection. Start by creating a sub-object with the name of the collection inside your plugins.js file.

// config/plugins.js

module.exports = () => ({
  //...
  meilisearch: {
    config: {
      restaurant: {}
    }
  }
})

Settings:

🏷 Custom index name
🪄 Transform entries
🤚 Filter entries
🏗 Add Meilisearch settings
🔎 Entries query
🔐 Selectively index private fields

🏷 Custom index name

By default, when indexing a content-type in Meilisearch, the index in Meilisearch has the same name as the content-type. This behavior can be changed by setting the indexName property in the configuration file of the plugin.

To link a single collection to multiple indexes, you can assign an array of index names to the indexName property.

Example 1: Linking a Single Collection to a Single Index

In the following examples, the restaurant content-type in Meilisearch is called my_restaurant instead of the default restaurant.

// config/plugins.js

module.exports = () => ({
  //...
  meilisearch: {
    config: {
      restaurant: {
        indexName: "my_restaurants",
      }
    }
  }
})

// config/plugins.js

module.exports = () => ({
  //...
  meilisearch: {
    config: {
      restaurant: {
        indexName: ["my_restaurants"],
      }
    }
  }
})

It is possible to bind multiple content-types to the same index. They all have to share the same indexName.

For example if shoes and shirts should be bound to the same index, they must have the same indexName in the plugin configuration:

// config/plugins.js

module.exports = () => ({
  //...
  meilisearch: {
    config: {
      shirts: {
        indexName: ['products'],
      },
      shoes: {
        indexName: ['products'],
      },
    },
  },
})

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

Example 2: Linking a Single Collection to Multiple Indexes

Suppose you want the restaurant content-type to be indexed under both my_restaurants and all_food_places indexes in Meilisearch. You can achieve this by setting the indexName property to an array containing both index names, as shown in the configuration below:

// config/plugins.js

module.exports = () => ({
  //...
  meilisearch: {
    config: {
      restaurant: {
        indexName: ['my_restaurants', 'all_food_places'],
      }
    }
  }
})

disclaimer

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

For example, given two content-types:

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.

When removing shoes or shirts from Meilisearch, both are removed as it would require to much processing to only remove one. You can still re-index only one after that.

<p align="center">Example with two single types:</p> <p align="center"> <img src="./assets/same-index.gif" alt="Example of two content-types with same indexName" width="600"/> </p>

Examples can be found this directory.

🪄 Transform entries

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

Create the alteration function transformEntry in the plugin's configuration file. Before sending the data to Meilisearch, every entry passes through this function where the alteration is applied.

transformEntry can be synchronous or asynchronous.

You can find a lot of examples in this directory.

Example

For example, the restaurant content-type has a relation with the category content-type. Inside a restaurant entry the categories field contains an array of each category in an object format: [{ name: "Brunch" ...}, { name: "Italian ... }].

The following transforms categories in an array of strings containing only the name of the category:

// config/plugins.js

module.exports = {
  meilisearch: {
    config: {
      restaurant: {
        transformEntry({ entry }) { // can also be async
          return {
            ...entry,
            categories: entry.categories.map(category => category.name)
          }
        },
      }
    }
  },
}

Result:

  {
    "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.

Important: You should always return the id of the entry without any transformation to allow sync when unpublished or deleting some entries in Strapi.

🤚 Filter entries

You might want to filter out some entries. This is possible with the filterEntry. Imagine you don't like Alfredo's restaurant. You can filter out this specific entry.

filterEntry can be synchronous or asynchronous.

// config/plugins.js

module.exports = {
  meilisearch: {
    config: {
      restaurant: {
        filterEntry({ entry }) { // can also be async
          return entry.title !== `Alfredo`
        },
      },
    },
  },
}

Alfredo's restaurant is not added to Meilisearch.

🏗 Add Meilisearch settings

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 the settings field in the plugin configuration file.

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

For example

module.exports = {
  meilisearch: {
    config: {
      restaurant: {
        settings: {
          filterableAttributes: ['categories'],
          synonyms: {
            healthy: ['pokeball', 'vegan']
          }
        }
      }
    }