MeiliSearch
Open-source search engine for your storefront
MedusaJS v2 Meilisearch plugin
Meilisearch for Medusa v2 catalogs: full-text and hybrid search over products and categories, plus store endpoints you can swap in for and without your storefront noticing.
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, including atomic index swaps for rebuilds without downtime, 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
- Store endpoints that keep native pricing, tax, , sales-channel scoping, filters and sorts
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.
The server floor comes from index swapping: the plugin's reindex strategy uses the field that Meilisearch 1.20 added to . Medusa 2.19 itself still runs on Node 20.19+, but this plugin is built and tested on Node 22 only.
The Meilisearch JS client stays on , the last version published as CommonJS.
Installation
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 . | |
| Index settings (synonyms, stop words, typo tolerance, …). | ||
| 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. | |
| 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 outside . 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 ().
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 admin status card 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
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:
Store API endpoints
All four endpoints accept the Meilisearch-specific parameters , , , , , and (a raw Meilisearch filter expression).
Everything the native accepts, plus the parameters above. Without it behaves exactly like the native route. With one, Meilisearch supplies the matching product ids and their ranking, and the response is hydrated natively — calculated prices, tax, , sales-channel scoping.
Response: .
Same idea against the native . Response: .
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: , , , , .
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
Add search to the Medusa Next.js starter
See nextjs/README.md.
FAQ
- Product categories and tags
- Product variant prices
- Product search prices
- Semantic search
- Migrating from v1
Contributing
Issues and pull requests are welcome at github.com/rokmohar/medusa-plugin-meilisearch.