[8bittitan]

Docusaurus is upgrading to DocSearch v5 (meta/docusaurus#12406) and needs to combine the filters it builds from the current page (language, version tags) with the facetFilters a site sets in its config. It currently carries its own merge logic for this, and the maintainers asked for it to live in DocSearch instead of being maintained on their side.

This adds a mergeFacetFilters helper, exposed from a new @docsearch/react/utils subpath. It's a separate entry so consumers can import it without pulling in any components. The only runtime dependency is getFacetFilterKey, and the file it comes from imports types only.

Why the merge isn't a plain concat

Algolia treats top-level entries as AND and nested arrays as OR. If a page filter says language:en and the site config says language:es, joining them as AND returns nothing, since a record has one language. The helper follows how faceted search and the facet bar here already behave: the same facet across inputs is ORed, and different facets are ANDed.

The rules I kept narrow on purpose, so the helper doesn't guess what a caller meant:

• Only inputs are merged with each other. Structure inside a single input is left alone, so ['_tags:docs', '_tags:v2'] stays an AND.
• Negations (status:-draft) are never merged, so exclusions add up instead of being undone.
• OR groups that mix facets are passed through as-is.
• Duplicate values are dropped from merged groups.

Because this ORs values, it can widen a base filter. facetFilters aren't access control (secured API keys are), so I don't think that's a concern, but it's worth knowing if you use this for anything restrictive.

Testing

Unit tests cover the cases above, including the "multiple filters with AND and OR" example from the Algolia docs.

bun run test --run packages/docsearch-react/src/utils/__tests__/mergeFacetFilters.test.ts

To check the export after a build:

bun run --filter @docsearch/react build

Then confirm packages/docsearch-react/dist/esm/utils.js and utils.d.ts exist, and try import { mergeFacetFilters } from '@docsearch/react/utils' from a consumer. Some calls worth trying:

mergeFacetFilters(['language:en', ['tag:a', 'tag:b']], ['language:es']);
// [['language:en', 'language:es'], ['tag:a', 'tag:b']]

mergeFacetFilters('status:-draft', 'status:-archived');
// ['status:-draft', 'status:-archived']

mergeFacetFilters(['_tags:docs', '_tags:v2'], ['_tags:v3']);
// ['_tags:docs', '_tags:v2', '_tags:v3']

[netlify]

✅ Deploy Preview for docsearch-demo ready!

Name	Link
🔨 Latest commit	22aca8c
🔍 Latest deploy log	https://app.netlify.com/projects/docsearch-demo/deploys/6ae23dce6d5a9b71f1007b8a
😎 Deploy Preview	https://deploy-preview-3066--docsearch-demo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for docsearch ready!

Name	Link
🔨 Latest commit	22aca8c
🔍 Latest deploy log	https://app.netlify.com/projects/docsearch/deploys/6ae23dce871970f8bfbf926a
😎 Deploy Preview	https://deploy-preview-3066--docsearch.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.