MeiliSearch
Open-source search engine for your storefront
Meilisearch plugin for Medusa
Meilisearch for Medusa v2 catalogs: full-text and hybrid search over products and categories, plus store endpoints that mirror and with Meilisearch ranking.
- How it fits together
- What you get
- Compatibility
- Installation
- Configuration
- Internationalization
- Semantic search
- Querying from code
- Storefront search with
- Store API endpoints
- Admin API endpoints
- Environment variables
- docker-compose
- Documentation
- Changelog
- Contributing
- Security
- License
How it fits together
Medusa 2.19.0 introduced a Search Module of its own, and from v2.0.0 this plugin plugs into it as the Meilisearch engine behind it. The division of labour:
| Who | Does what |
|---|---|
| Medusa's Search Module | Creates and migrates indexes, seeds them, batches writes, routes catalog events, rebuilds on drift |
| This plugin's provider | Turns index declarations into Meilisearch settings and queries into Meilisearch requests |
| This plugin's factories | Ship ready-made product and category declarations you can extend |
| This plugin's routes and admin page | Native-parity store search, plus a settings screen for indexes and reindexing |
Practically, that means you no longer run any indexing code yourself. You declare what an index holds; Medusa keeps it filled.
What you get
- Every method of the provider contract, so the module can rebuild an index into a fresh version and activate it, batched multi-search, and write-task tracking so seeding knows when a batch has actually landed
- Declared field weights compiled into Meilisearch relevance ordering, with filterable, sortable and facetable attributes derived from the same declaration
- Value, range and statistical facets; highlighting and cropped snippets; estimated or exhaustive counts
- Hybrid search over Meilisearch embedders — OpenAI, Ollama, Hugging Face, a REST endpoint, or vectors you compute
- One index per locale, translated through Medusa's Translation Module
- An escape hatch at every level: raw Meilisearch settings per index, raw Meilisearch parameters per query
- Drop-in engine for Medusa's own and , with product hits scoped to the publishable key's sales channels
- Store endpoints that keep native pricing, tax, and sales-channel scoping
Compatibility
| Plugin | Medusa | Meilisearch server | Node |
|---|---|---|---|
The 2.19 release removed the search interface the v1 line was written against, so the two lines do not overlap: v1 stops at Medusa 2.18, v2 starts at 2.19. Coming from v1, work through the upgrade guide.
Every 2.x row is pinned to one Medusa minor rather than a floor, because the Search Module has changed between minors, and the ranges are so a newer plugin minor built for another Medusa minor is never installed by accident. Medusa 2.20 made asynchronous and made it resolve to index records, which 2.0.0 cannot read. Medusa 2.21 then narrowed index settings to what every engine can honour, changed the seed function to yield mutations rather than documents, and took over index swapping. Engine-specific settings, localized indexes included, now live under . Medusa 2.22 left the module unchanged; 2.4.0 moves the peer range to it.
Within the 2.21 line, 2.3.0 requires Medusa 2.21.1, the patch that shipped and .
Meilisearch 1.20 is the minimum supported server version. CI runs on Node 22.
The Meilisearch JS client is , which is published as ES modules only. The plugin's CommonJS build loads it via Node's , hence the Node 22.12 floor.
Installation
Medusa itself is a peer dependency, so pick the plugin version that matches your Medusa minor from the compatibility table.
Configuration
Register the plugin (for its API routes and admin page) and the Search Module with this package as its provider:
Then declare your indexes under . The application loads every file in that directory and hands the declarations to the Search Module:
Create the indexes, then start the app:
creates and migrates the physical Meilisearch indexes. On boot the Search Module seeds any index that was just created, was emptied, or whose declaration changed; from then on it keeps them current from events. Indexes live in Meilisearch and are never recreated at startup.
Provider options
| Option | Type | Description |
|---|---|---|
| Meilisearch client config. is required; is optional for keyless instances. | ||
| Meilisearch embedders applied to every index this provider manages. Keys are the embedder names. | ||
| Meilisearch settings applied below the settings derived from each declaration, e.g. . | ||
| How long to wait for a deferred write. Default . | ||
| How often to poll for a write to land. Default . |
Index factory options
Both and take the same options and always return an array of declarations (one per locale).
| Option | Default | Description |
|---|---|---|
| / | Base index name. | |
| the module's default provider | Provider identifier this index binds to. | |
| Document primary key. | ||
| the default schema | Replaces the field schema. Use . | |
| Typo tolerance and distinct attribute, plus for engine settings. | ||
| the default selection | Extra paths to fetch while seeding and ingesting. | |
| / | filters. | |
| pick of the declared paths | Maps an entity to a search document. Synchronous; the document must keep . | |
| – | context (e.g. a pricing context), or a function of the ingestion context. | |
| Seed page size. | ||
| product / category events, both namespaces | Events this index reacts to. | |
| the default routing table | Turns an event into index mutations. | |
| – | BCP-47 locales; emits one index per locale. | |
| first entry of | Which locale keeps the bare index name. |
Extending the default schema:
Meilisearch has no per-attribute weights — relevance follows the order of — so declared weights become that ordering.
Worker mode
Seeding and event ingestion run on instances whose is or , not . In a split deployment, install and configure the plugin on the worker instance too, or its indexes will stay empty.
Internationalization
Pass to a factory to get one index per locale. The default locale keeps the bare name, the others are suffixed:
This registers , and . Each index declares its locale, seeds and ingests through so documents carry the translated values, and tells Meilisearch which analyzer to use. Localized reads require Medusa's Translation Module ().
Meilisearch ships analyzers for a fixed list of languages. A locale outside it — Icelandic, for one — still gets its own index, its translated documents and its locale routing; only the analyzer declaration is left out, so Meilisearch detects the language itself.
Store requests select an index by locale: (or the header). Region variants fall back to the same language, so uses the index when no index exists, and an unknown locale falls back to the default index. addresses one index directly.
Semantic search
Configure Meilisearch embedders on the provider and query them with :
Declare embedders under on an index to scope them to that index — the AI-Powered Semantic Search card on the admin page reads declarations, so per-index embedders also show up there. Pre-computed embeddings are supported by declaring a field. See docs/semantic-search.md for Ollama and OpenAI walkthroughs.
Querying from code
In an API route, workflow step or subscriber, resolve the Search Module from the container:
does the same and additionally hydrates fields the index does not hold. Anything Meilisearch cannot express — and filters, cursor pagination, the matching strategy, query-time typo tolerance, ascending relevance — raises an error instead of silently returning different results. Raw Meilisearch parameters go through .
Reindex on demand:
Storefront search with
Medusa's own store search route works against these indexes once you allow them. Add the native middleware to your application's :
Allowed names are the registered index names, so a localized setup lists each one ( and so on) and the storefront picks the index for its locale.
Medusa narrows every product index to and to the sales channels of the request's publishable key. The product declaration carries a filterable for that, filled from . Editing a product's channels emits and re-indexes it; adding products from the sales channel side emits nothing, so reindex after bulk assignments.
The route returns indexed fields only, so anything a storefront card shows has to be declared on the index. For calculated prices, inventory and other per-request values use below.
The InstantSearch adapter speaks to the same route:
Store API endpoints
Every store request needs the header.
The hydrated and endpoints are the way to combine Meilisearch ranking with native pricing. The endpoints predate the native route and overlap with it; prefer in new storefronts.
All four endpoints accept the Meilisearch-specific parameters , , , , , and (a raw Meilisearch filter expression). , and index belong to the endpoints only; the hydrated endpoints validate the rest of their query like the native routes.
Everything the native accepts, plus the parameters above. Without or it behaves like the native route. With either, Meilisearch supplies the matching product ids, their ranking and the , and the response is hydrated natively: calculated prices, tax and . Currency follows ; request for stock.
Like , the search is narrowed to published products and to the request's sales channels (the you pass, or every channel of the publishable key), on each of and the index declares filterable. The default product index declares both. When searching:
- Results come back in relevance order; a native is ignored.
- Native filters such as or apply to the page Meilisearch returns, so a page can hold fewer than products and does not reflect them. Express such filters through on indexed fields to keep paging exact.
Response: .
Same idea against the native : active, public categories only, and products reached through them are published ones. Response: like the native route, plus the same list under , the key earlier versions used.
and
Raw engine hits, with no database read: , plus when requested and / for a hybrid query. Each hit carries the index's retrievable fields and . Additional parameters: , , , , . These endpoints are not narrowed to the key's sales channels; pass a on yourself, or use .
Admin API endpoints
| Endpoint | Description |
|---|---|
| Registered indexes with their entity, locales and retrievable fields. | |
| Starts a reindex () and returns immediately. | |
| Raw product hits, same body as the store endpoint. | |
| Raw category hits. | |
| Semantic-search status derived from the registered declarations. |
Medusa's own dashboard search uses the core endpoint and picks up these indexes automatically.
Environment variables
docker-compose
Documentation
Changelog
See CHANGELOG.md and the GitHub releases.
Contributing
Issues and pull requests are welcome. CONTRIBUTING.md covers the development setup, trying changes in a Medusa app, and the pull request checklist. Everyone taking part follows the code of conduct.
Security
Report vulnerabilities privately, as described in SECURITY.md.
License
MIT © Rok Mohar

