MeiliSearch

MedusaJS v2 MeiliSearch Plugin with i18n Support

This plugin integrates MeiliSearch with your Medusa e-commerce store and adds support for internationalization (i18n) of your product catalog.

Features

• Full-text search for your Medusa store
• Real-time indexing
• Typo-tolerance
• Faceted search
• Internationalization (i18n) support with multiple strategies:
  1. Separate index per language
  2. Language-specific fields with suffix
• Flexible translation configuration
• Custom field transformations
• Automatic field detection

Installation

Run the following command to install the plugin with npm:

1
npm install --save @rokmohar/medusa-plugin-meilisearch

Or with yarn:

1
yarn add @rokmohar/medusa-plugin-meilisearch

Upgrade to v1.0

This step is required only if you are upgrading from previous version to v1.0.

• The plugin now supports new MedusaJS plugin system.
• Subscribers are included in the plugin.
• You don't need custom subscribers anymore, you can remove them.

⚠️ MedusaJS v2.4.0 or newer

This plugin is only for MedusaJS v2.4.0 or newer.

If you are using MedusaJS v2.3.1 or older, please use the older version of this plugin.

Configuration

Add the plugin to your Copy to clipboardmedusa-config.ts file:

1234567891011121314151617181920
import { loadEnv, defineConfig } from '@medusajs/framework/utils'
import { MeilisearchPluginOptions } from '@rokmohar/medusa-plugin-meilisearch'

loadEnv(process.env.NODE_ENV || 'development', process.cwd())

module.exports = defineConfig({
  // ... other config
  plugins: [
    // ... other plugins
    {
      resolve: '@rokmohar/medusa-plugin-meilisearch',
      options: {
        config: {
          host: process.env.MEILISEARCH_HOST ?? '',
          apiKey: process.env.MEILISEARCH_API_KEY ?? '',
        },
        settings: {
          // The key is used as the index name in Meilisearch
          products: {
            // Required: Index type

i18n Configuration

The plugin supports two main strategies for handling translations, with flexible configuration options for each.

Basic Configuration

123456789101112
{
  i18n: {
    // Choose strategy: 'separate-index' or 'field-suffix'
    strategy: 'field-suffix',
    // List of supported languages
    languages: ['en', 'fr', 'de'],
    // Default language to fall back to
    defaultLanguage: 'en',
    // Optional: List of translatable fields
    translatableFields: ['title', 'description', 'handle']
  }
}

Advanced Field Configuration

You can provide detailed configuration for each translatable field:

1234567891011121314151617181920
{
  i18n: {
    strategy: 'field-suffix',
    languages: ['en', 'fr', 'de'],
    defaultLanguage: 'en',
    translatableFields: [
      // Simple field name
      'title',

      // Field with different target name
      {
        source: 'description',
        target: 'content'  // Will be indexed as content_en, content_fr, etc.
      },

      // Field with transformation
      {
        source: 'handle',
        transform: (value) => value.toLowerCase().replace(/\s+/g, '-')
      }

Custom Translation Transformer

The plugin provides a flexible way to transform your products with custom translations. Instead of relying on specific storage formats, you can provide translations directly to the transformer:

1234567891011121314151617181920
import { transformProduct } from '@rokmohar/medusa-plugin-meilisearch'

const getProductTranslations = async (productId: string) => {
  // Example: fetch from your translation service/database
  return {
    title: [
      { language_code: 'en', value: 'Blue T-Shirt' },
      { language_code: 'fr', value: 'T-Shirt Bleu' },
    ],
    description: [
      { language_code: 'en', value: 'A comfortable blue t-shirt' },
      { language_code: 'fr', value: 'Un t-shirt bleu confortable' },
    ],
  }
}

// Example usage in your custom transformer
const customTransformer = async (product, options) => {
  const translations = await getProductTranslations(product.id)

i18n Strategies

1. Separate Index per Language

This strategy creates a separate MeiliSearch index for each language. For example, if your base index is named "products", it will create:

• products_en
• products_fr
• products_de

Benefits:

• Better performance for language-specific searches
• Language-specific settings and ranking rules
• Cleaner index structure

2. Language-specific Fields with Suffix

This strategy adds language suffixes to translatable fields in the same index. For example:

• title_en, title_fr, title_de
• description_en, description_fr, description_de

Benefits:

• Single index to maintain
• Ability to search across all languages at once
• Smaller storage requirements

API Endpoints

Search for Hits

1
GET /store/meilisearch/hits

Query Parameters:

• Copy to clipboardquery: Search query string
• Copy to clipboardlimit: (Optional) Limit results from search
• Copy to clipboardoffset: (Optional) Offset results from search
• Copy to clipboardlanguage: (Optional) Language code

Examples:

12
# Basic search in French
GET /store/meilisearch/hits?query=shirt&language=fr

Auto-detection of Translatable Fields

If no translatable fields are specified and using the field-suffix strategy, the plugin will automatically detect string fields as translatable. You can override this by explicitly specifying the fields:

123456789
{
  i18n: {
    strategy: 'field-suffix',
    languages: ['en', 'fr'],
    defaultLanguage: 'en',
    // Only these fields will be translatable
    translatableFields: ['title', 'description']
  }
}

ENV variables

Add the environment variables to your Copy to clipboard.env and Copy to clipboard.env.template file:

123
# ... others vars
MEILISEARCH_HOST=
MEILISEARCH_API_KEY=

If you want to use with the Copy to clipboarddocker-compose from this README, use the following values:

123
# ... others vars
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_API_KEY=ms

docker-compose

You can add the following configuration for Meilisearch to your Copy to clipboarddocker-compose.yml:

12345678910111213141516
services:
  # ... other services

  meilisearch:
    image: getmeili/meilisearch:latest
    ports:
      - '7700:7700'
    volumes:
      - ~/data.ms:/data.ms
    environment:
      - MEILI_MASTER_KEY=ms
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:7700']
      interval: 10s
      timeout: 5s
      retries: 5

Add search to Medusa NextJS starter

You can find instructions on how to add search to a Medusa NextJS starter inside the nextjs folder.

Contributing

Feel free to open issues and pull requests!