The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
docs(MM2-2728): enhance Algolia integration documentation and update default product settings (#779)
Tomasz Buras26206801c83e
diff --git a/apps/docs/integrations/algolia.mdx b/apps/docs/integrations/algolia.mdxindex 07f8a3545..02071c828 100644--- a/apps/docs/integrations/algolia.mdx+++ b/apps/docs/integrations/algolia.mdx@@ -10,12 +10,196 @@ Mercur uses <a href="https://www.algolia.com/">Algolia</a> as a search engine toIn order to use Algolia, an account is needed. After registration, enter `ALGOLIA_APP_ID` and `ALGOLIA_API_KEY` obtained from the Algolia dashboard into the `.env` file.+```bash+ALGOLIA_APP_ID=your_app_id+ALGOLIA_API_KEY=your_admin_api_key+```++For the storefront, you also need to configure the public search key:++```bash+NEXT_PUBLIC_ALGOLIA_ID=your_app_id+NEXT_PUBLIC_ALGOLIA_SEARCH_KEY=your_search_only_api_key+```+### Configuration<a href="https://www.algolia.com/doc/rest-api/search/#tag/Indices/operation/setSettings">See the full settings reference here!</a>+> **Important:** The settings below are configured for the **default Mercur storefront**. If you're using a custom storefront with different filtering requirements, you'll need to adjust `attributesForFaceting` based on your specific filters. See the [Custom Storefront Configuration](#custom-storefront-configuration) section below.++#### Understanding attributesForFaceting++The Algolia `attributesForFaceting` setting is **directly tied to the filters used in your storefront code**.++**The Rule:**+- Every attribute you filter by in your storefront → Must be declared in `attributesForFaceting`+- Without this declaration, Algolia will ignore the filter or return 0 results++**Example:**+```javascript+// If your storefront uses this filter:+filters: "seller.handle:vendor-name AND supported_countries:pl"++// Algolia MUST have:+attributesForFaceting: [+ "filterOnly(seller.handle)",+ "filterOnly(supported_countries)"+]+```++#### Default Storefront Configuration++The default Mercur storefront uses the following filters in product listing pages:++**Repository:** [mercurjs/b2c-marketplace-storefront](https://github.com/mercurjs/b2c-marketplace-storefront)++**Location:** `src/components/sections/ProductListing/AlgoliaProductsListing.tsx`++```javascript+// Default storefront filters:+NOT seller:null AND+NOT seller.store_status:SUSPENDED AND+supported_countries:${locale} AND+variants.prices.currency_code:${currency_code} AND+variants.prices.amount > 0+```++Additionally, the default storefront supports faceted filtering by:+- `variants.condition` - Product condition (e.g., new, used, refurbished)+- `variants.color` - Product color options+- `variants.size` - Product size options++##### Recommended Algolia Settings for Default Storefront++**Important:** Use the official configuration file from the storefront repository to ensure compatibility:++👉 **[View and download algolia-config.json](https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/algolia-config.json)**++This configuration includes all necessary settings for:+- `attributesForFaceting` - Required for filtering by category, seller, country, currency, etc.+- `searchableAttributes` - Product fields that are searchable+- Ranking and relevance settings+- Facet ordering (color, size, condition)++**How to apply:**++1. **Via Algolia Dashboard (recommended):**+ - Download the [algolia-config.json](https://github.com/mercurjs/b2c-marketplace-storefront/blob/main/algolia-config.json) file+ - In Algolia Dashboard, go to your product index+ - Select "Import configuration" from the "Manage index" dropdown+ - Upload the downloaded file++2. **Via API:**+ - Use the Algolia API to update index settings programmatically+ - See [Algolia setSettings documentation](https://www.algolia.com/doc/rest-api/search/#tag/Indices/operation/setSettings)++**Key Configuration Elements:**++The official configuration includes these critical settings:++- **attributesForFaceting** - Enables filtering by:+ - `categories.id` - Filter products by category+ - `seller.handle` - Filter products by vendor/seller+ - `seller.store_status` - Filter out suspended sellers+ - `seller.id` - Filter by specific seller ID+ - `supported_countries` - Geographic filtering+ - `variants.prices.currency_code` - Currency-specific filtering+ - `variants.color`, `variants.size`, `variants.condition` - Product attributes+ - `attribute_values.name` and `attribute_values.value` - Custom attributes++- **searchableAttributes** - Defines which fields are searchable in text queries++- **facetOrdering** - Controls the order and display of facets in the storefront++**Prefix Explanation:**+- `filterOnly(attr)` - Attribute can only be used for filtering (more memory efficient)+- `searchable(attr)` - Attribute can be used for both filtering and text search++**Important:** After updating index settings in Algolia, re-sync your products to ensure the new configuration is applied correctly.++#### Custom Storefront Configuration++If you're building a custom storefront or modifying the default one, follow these steps:++##### 1. Identify Your Filters++Search your storefront code for Algolia filter usage. Common locations:+- Product listing components+- Search components+- Category/collection pages++```javascript+// Example: Finding filters in your code+const filters = `brand:${brand} AND color:${color} AND price_range:${range}`+```++##### 2. Map Filters to attributesForFaceting++For each attribute used in filters, add it to `attributesForFaceting`:++```json+{+ "attributesForFaceting": [+ "filterOnly(brand)", // For: brand:Nike+ "filterOnly(color)", // For: color:red+ "filterOnly(price_range)" // For: price_range:100-500+ ]+}+```++##### 3. Choose the Right Prefix++- Use `filterOnly()` for attributes that only need filtering (most common, more efficient)+- Use `searchable()` for attributes that should also be searchable via text query++##### 4. Update and Test++1. Update your Algolia index settings via dashboard or API+2. Re-sync your products if needed+3. Test filtering in your storefront to ensure it works++**Example Custom Configuration:**++If your custom storefront filters by brand, color, and collection:++```javascript+// Your custom storefront code:+const filters = `+ brand:${selectedBrand} AND+ color:${selectedColor} AND+ collection.id:${collectionId}+`+```++Required Algolia settings:++```json+{+ "attributesForFaceting": [+ "filterOnly(brand)",+ "filterOnly(color)",+ "filterOnly(collection.id)"+ ]+}+```++**Important:** After updating index settings in Algolia, re-sync your products to ensure the new configuration is applied correctly.++#### Product Visibility Requirements++For a product to be visible on the **default Mercur storefront** via Algolia search, it must meet **all** of the following conditions:++1. **Product Status:** Must be `published`+2. **Seller Assignment:** Product must have an assigned seller with status `ACTIVE` (not `SUSPENDED`)+3. **Geographic Availability:** Product's `supported_countries` must include the target country code+4. **Pricing:** All variants must have prices in the appropriate currency with `amount > 0`+5. **Inventory:** Variants must have properly configured inventory locations with fulfillment sets for the target country++> **Note:** If you're using a custom storefront, your visibility requirements may differ based on your filtering logic.+### EventsIn order to persist consistency between database and Algolia, every time any change in indexed entities happens an event is emitted, for example:@@ -32,3 +216,44 @@ We use also intermediate events, that also should trigger synchronization with A- `algolia.intermediate.inventory_item.changed`Each event is connected to the subscriber, which is responsible for refetching the entity and updating it in Algolia.++### Troubleshooting++#### Products not showing on storefront++If your products are indexed in Algolia but not appearing on the storefront, verify:++1. **Check attributesForFaceting** - Ensure all attributes used in your storefront filters are declared in `attributesForFaceting`+2. **Verify filter values** - Check that products have the values you're filtering by (e.g., `supported_countries` contains the target country)+3. **Review pricing** - Ensure all variants have prices in the correct currency (if you filter by currency)+4. **Confirm seller status** - If filtering by seller status, verify it's `ACTIVE` and not `SUSPENDED`+5. **Check product status** - Ensure product status is `published`+6. **Inspect Algolia Dashboard** - View your index in Algolia Dashboard to see actual data and test filters++#### Common Issues++**Issue: "No results" on product listing page**++Most common cause: Missing `attributesForFaceting` configuration.++Solution:+1. Check your storefront code to see what filters are applied+2. Compare with your Algolia `attributesForFaceting` settings+3. Add any missing attributes to the Algolia configuration+4. Re-sync products if needed++**Issue: Filters not working**++Solution:+- Verify the attribute exists in your product data in Algolia+- Check that the attribute is declared in `attributesForFaceting`+- Use `filterOnly()` prefix for filtering-only attributes+- Use `searchable()` prefix if you also need to search by this attribute++**Issue: Products missing after adding new filter**++Solution:+- New filters require corresponding `attributesForFaceting` entries+- Update Algolia index settings first+- Then add the filter to your storefront code+- Products without the filtered attribute value will be excluded (this is expected)diff --git a/packages/registry/src/algolia/modules/algolia/service.ts b/packages/registry/src/algolia/modules/algolia/service.tsindex 0b9cf8d2e..a6ae132a0 100644--- a/packages/registry/src/algolia/modules/algolia/service.ts+++ b/packages/registry/src/algolia/modules/algolia/service.ts@@ -5,79 +5,79 @@ import {IndexSettings,SearchParams,SearchResponse,- algoliasearch-} from 'algoliasearch'+ algoliasearch,+} from "algoliasearch";-import { AlgoliaEntity, IndexType } from './types'+import { AlgoliaEntity, IndexType } from "./types";type ModuleOptions = {- appId: string- apiKey: string-}+ appId: string;+ apiKey: string;+};export const defaultProductSettings: IndexSettings = {searchableAttributes: [- 'title',- 'subtitle',- 'tags.value',- 'type.value',- 'categories.name',- 'collection.title',- 'variants.title'- ]-}+ "title",+ "subtitle",+ "tags.value",+ "type.value",+ "categories.name",+ "collection.title",+ "variants.title",+ ],+};class AlgoliaModuleService {- private options_: ModuleOptions- private algolia_: Algoliasearch+ private options_: ModuleOptions;+ private algolia_: Algoliasearch;constructor(_: unknown, options: ModuleOptions) {- this.options_ = options- this.algolia_ = algoliasearch(this.options_.appId, this.options_.apiKey)+ this.options_ = options;+ this.algolia_ = algoliasearch(this.options_.appId, this.options_.apiKey);}getAppId() {- return this.options_.appId+ return this.options_.appId;}checkIndex(index: IndexType) {return this.algolia_.indexExists({- indexName: index- })+ indexName: index,+ });}updateSettings(index: IndexType, settings: IndexSettings) {return this.algolia_.setSettings({indexName: index,- indexSettings: settings- })+ indexSettings: settings,+ });}batch(type: IndexType, toAdd: AlgoliaEntity[], toDelete: string[]) {const addRequests: BatchRequest[] = toAdd.map((entity) => {return {- action: 'addObject' as Action,+ action: "addObject" as Action,objectID: entity.id,- body: entity- }- })+ body: entity,+ };+ });const deleteRequests: BatchRequest[] = toDelete.map((id) => {return {- action: 'deleteObject' as Action,+ action: "deleteObject" as Action,objectID: id,- body: {}- }- })+ body: {},+ };+ });- const requests = [...addRequests, ...deleteRequests]+ const requests = [...addRequests, ...deleteRequests];return this.algolia_.batch({indexName: type,batchWriteParams: {- requests- }- })+ requests,+ },+ });}batchUpsert(type: IndexType, entities: AlgoliaEntity[]) {@@ -86,13 +86,13 @@ class AlgoliaModuleService {batchWriteParams: {requests: entities.map((entity) => {return {- action: 'addObject',+ action: "addObject",objectID: entity.id,- body: entity- }- })- }- })+ body: entity,+ };+ }),+ },+ });}batchDelete(type: IndexType, ids: string[]) {@@ -101,50 +101,50 @@ class AlgoliaModuleService {batchWriteParams: {requests: ids.map((id) => {return {- action: 'deleteObject',+ action: "deleteObject",objectID: id,- body: {}- }- })- }- })+ body: {},+ };+ }),+ },+ });}upsert(type: IndexType, entity: AlgoliaEntity) {return this.algolia_.addOrUpdateObject({indexName: type,objectID: entity.id,- body: entity- })+ body: entity,+ });}delete(type: IndexType, id: string) {return this.algolia_.deleteObject({indexName: type,- objectID: id- })+ objectID: id,+ });}partialUpdate(type: IndexType,- entity: Partial<AlgoliaEntity> & { id: string }+ entity: Partial<AlgoliaEntity> & { id: string },) {return this.algolia_.partialUpdateObject({indexName: type,objectID: entity.id,- attributesToUpdate: { ...entity }- })+ attributesToUpdate: { ...entity },+ });}search<T = Record<string, unknown>>(indexName: IndexType,- params: SearchParams+ params: SearchParams,): Promise<SearchResponse<T>> {return this.algolia_.searchSingleIndex<T>({indexName,- searchParams: params- })+ searchParams: params,+ });}}-export default AlgoliaModuleService+export default AlgoliaModuleService;