Elasticsearch

Name: Elasticsearch
Author: Peterborodatyy

Elasticsearch search plugin for Medusa v2

npm install medusa-plugin-elasticsearch

Medusa Elasticsearch Plugin

Elasticsearch search plugin for Medusa v2. Provides automatic product and category indexing, full-text search, and admin sync capabilities powered by Elasticsearch.

Features

Product and category indexing with real-time sync on create, update, and delete events
Full reindex via admin API endpoint or scheduled job (daily at midnight)
Batch syncing with pagination (50 items per batch) for large catalogs
Smart filtering -- only published products and active/non-internal categories are indexed
Custom document transformers per index type
Configurable Elasticsearch mappings, analyzers, and tokenizers
Search API for products () and categories ()
Admin API at with authentication
Admin UI settings page at with sync button and search testing
Workflow compensation -- automatic rollback on indexing failures
Built as a Medusa v2 module with workflows, subscribers, and scheduled jobs

Prerequisites

Medusa v2 application (v2.5.0+)
Elasticsearch 9.x instance or Elastic Cloud

Installation

1. Install the plugin in your Medusa project:

npm install medusa-plugin-elasticsearch

2. Set environment variables in :

1ELASTIC_CLOUD_ID=your_cloud_id
2ELASTIC_USER_NAME=your_username
3ELASTIC_PASSWORD=your_password

Or for a local Elasticsearch 9.x instance:

ELASTIC_NODE=http://localhost:9200

3. Register the plugin and module in :

1import { defineConfig } from "@medusajs/framework/utils"
2
3export default defineConfig({
// Register the plugin (loads subscribers, API routes, workflows, jobs)
plugins: [
  {
    resolve: "medusa-plugin-elasticsearch",
    options: {},
  },
],
// Register the Elasticsearch module
modules: [
  {
    resolve: "medusa-plugin-elasticsearch/modules/elasticsearch",
    options: {
      config: {
        // Option A: Elastic Cloud
        cloud: {
          id: process.env.ELASTIC_CLOUD_ID,
        },
        auth: {
          username: process.env.ELASTIC_USER_NAME,
          password: process.env.ELASTIC_PASSWORD,
        },
        // Option B: Local instance
        // node: process.env.ELASTIC_NODE,
      },
      settings: {
        products: {
          // Optional: custom Elasticsearch mappings
          mappings: {
            properties: {
              id: { type: "keyword" },
              title: { type: "text" },
              description: { type: "text" },
              handle: { type: "keyword" },
            },
          },
          // Optional: custom index settings (analyzers, tokenizers)
          settings: {
            analysis: {
              tokenizer: {
                autocomplete: {
                  type: "edge_ngram",
                  min_gram: 2,
                  max_gram: 10,
                  token_chars: ["letter", "digit"],
                },
              },
              analyzer: {
                autocomplete_index: {
                  type: "custom",
                  tokenizer: "autocomplete",
                  filter: ["lowercase"],
                },
              },
            },
          },
        },
        categories: {
          mappings: {
            properties: {
              id: { type: "keyword" },
              name: { type: "text" },
              handle: { type: "keyword" },
              description: { type: "text" },
            },
          },
        },
      },
    },
  },
],
74})

Options

Module Options

Name	Description	Required
	Elasticsearch client configuration (cloud, auth, node, etc.)	true
	Index configurations keyed by index name (, , or custom)	false

Index Options (per index in )

Name	Description	Required
	Custom document transformer function	false
	Elasticsearch mapping configuration	false
	Elasticsearch index settings (analyzers, tokenizers, normalizers)	false

API Endpoints

Store: Search Products

POST /store/products/search

Search products indexed in Elasticsearch. No authentication required.

Request body:

1{
2  "q": "sweatshirt",
3  "offset": 0,
4  "limit": 20,
5  "filter": {}
6}

Store: Search Categories

POST /store/categories/search

Search product categories. No authentication required.

Request body:

1{
2  "q": "electronics",
3  "offset": 0,
4  "limit": 20
5}

Response: Standard Elasticsearch search response with .

Admin: Trigger Full Sync

POST /admin/elasticsearch/sync

Triggers a full reindex of all products and categories. Requires admin authentication (session, bearer, or API key).

Response:

1{
2  "message": "Syncing products to Elasticsearch"
3}

The sync runs asynchronously, processing items in batches of 50.

Automatic Syncing

Real-time Events

The plugin automatically syncs on these events:

Products:

-- indexes the new product
-- re-indexes the updated product
-- removes the product from the index

Categories:

-- indexes the new category
-- re-indexes the updated category
-- removes the category from the index

Indexing Rules

Products: Only products are indexed. Draft/unpublished products are removed from the index.
Categories: Only and categories are indexed. Inactive or internal categories are removed.

Scheduled Reindex

A scheduled job runs daily at midnight to trigger a full reindex via the event.

Manual Reindex

Use the admin API endpoint or emit the event directly:

1const eventBus = container.resolve("event_bus")
2await eventBus.emit({ name: "elasticsearch.sync", data: {} })

Workflows

The plugin exports workflows for direct use:

1import {
2  syncProductsToElasticsearchWorkflow,
3  deleteProductsFromElasticsearchWorkflow,
4  syncCategoriesToElasticsearchWorkflow,
5  deleteCategoriesFromElasticsearchWorkflow,
6} from "medusa-plugin-elasticsearch/workflows"
7
8// Sync specific products
9await syncProductsToElasticsearchWorkflow(container).run({
10  input: { ids: ["prod_01ABC"] },
11})
12
13// Sync specific categories
14await syncCategoriesToElasticsearchWorkflow(container).run({
15  input: { ids: ["pcat_01ABC"] },
16})
17
18// Delete from index
19await deleteProductsFromElasticsearchWorkflow(container).run({
20  input: { ids: ["prod_01ABC"] },
21})
22
23await deleteCategoriesFromElasticsearchWorkflow(container).run({
24  input: { ids: ["pcat_01ABC"] },
25})

Custom Transformer

By default, products are indexed with a built-in transformer that flattens variant data, tags, categories, and collections. Categories are indexed with parent/children metadata. You can override either:

1{
settings: {
  products: {
    transformer: (product) => ({
      id: product.id,
      title: product.title,
      description: product.description,
      handle: product.handle,
      thumbnail: product.thumbnail,
    }),
  },
  categories: {
    transformer: (category) => ({
      id: category.id,
      name: category.name,
      handle: category.handle,
    }),
  },
},
20}

Architecture

1src/
admin/                        # Admin UI extension
  lib/sdk.ts                  # Medusa JS SDK client
  routes/settings/elasticsearch/
    page.tsx                  # Settings page (sync + search testing)
modules/elasticsearch/        # Elasticsearch module
  index.ts                    # Module definition (Module())
  service.ts                  # ES client service
  types.ts                    # Type definitions
  loaders/initialize.ts       # Index initialization on startup
subscribers/
  product-upsert.ts           # Sync on product.created / product.updated
  product-deleted.ts          # Remove on product.deleted
  category-upsert.ts          # Sync on product-category.created / updated
  category-deleted.ts         # Remove on product-category.deleted
  elasticsearch-sync.ts       # Full reindex (products + categories)
workflows/
  sync-products-to-elasticsearch.ts       # Fetch + index products
  delete-products-from-elasticsearch.ts   # Delete products from index
  sync-categories-to-elasticsearch.ts     # Fetch + index categories
  delete-categories-from-elasticsearch.ts # Delete categories from index
  index.ts                                # Workflow exports
api/
  middlewares.ts              # Validation + admin auth
  store/products/search/      # POST /store/products/search
  store/categories/search/    # POST /store/categories/search
  admin/elasticsearch/sync/   # POST /admin/elasticsearch/sync
jobs/
  elasticsearch-reindex.ts    # Daily scheduled reindex
utils/
  transformer.ts              # Default product + category transformers
types/
  index.ts                    # Public type exports

Roadmap

Planned features for future releases:

i18n / multi-language support -- index per locale or field-suffix strategy for multilingual storefronts
Admin UI extension -- dashboard widget with sync button, index status, and document counts
Configurable reindex schedule -- allow custom cron expressions via module options
Collection indexing -- sync product collections alongside products and categories
Aggregation helpers -- pre-built faceted search support (price ranges, categories, tags)
Geo-search support -- location-based product search leveraging Elasticsearch's geo queries
Index aliasing -- zero-downtime reindexing using Elasticsearch index aliases
Bulk reindex CLI command -- one-time full reindex via Medusa CLI

Elasticsearch

Medusa Elasticsearch Plugin

Features

Prerequisites

Installation

Options

Module Options

Index Options (per index in )

API Endpoints

Store: Search Products

Store: Search Categories

Admin: Trigger Full Sync

Automatic Syncing

Real-time Events

Indexing Rules

Scheduled Reindex

Manual Reindex

Workflows

Custom Transformer

Architecture

Roadmap

Additional Resources

Contributing

License

More in this category

MeiliSearch

MeiliSearch

Relewise

Elasticsearch

Medusa Elasticsearch Plugin

Features

Prerequisites

Installation

Options

Module Options

Index Options (per index in settings)

API Endpoints

Store: Search Products

Store: Search Categories

Admin: Trigger Full Sync

Automatic Syncing

Real-time Events

Indexing Rules

Scheduled Reindex

Manual Reindex

Workflows

Custom Transformer

Architecture

Roadmap

Additional Resources

Contributing

License

More in this category

MeiliSearch

MeiliSearch

Relewise

Index Options (per index in )