break(theme-search-algolia)!: upgrade to DocSearch v5 (AI-assisted) by 8bittitan · Pull Request #12406 · facebook/docusaurus

8bittitan · 2026-09-03T21:01:25Z

Motivation

Upgrades @docsearch/react from v4 to v5 and removes the DocSearch v3
compatibility layer that was carried during the v3/v4 transition period.

DocSearch v5 drops the old v3 APIs and introduces multi-index search and
Agent Studio-based Ask AI, neither of which can be expressed with the previous
single-index (indexName + top-level searchParameters) configuration. This PR
migrates the theme config surface accordingly.

This is the first PR in a stack. Documentation updates (search.mdx) will
follow in a separate stacked PR.

What changed

Bump @docsearch/react to ^5.0.4 (+ lockfile)
Replace algolia.indexName and top-level algolia.searchParameters with an
algolia.indices array (accepts string or {name, searchParameters} entries)
Load the search vs. Ask AI modal via dedicated dynamic entry points
(@docsearch/react/modal / @docsearch/react/askaiModal)
Migrate Ask AI to Agent Studio: assistantId → agentId, per-index
searchParameters, and new memory / promptSuggestions options
Convert contextual facetFilters into Agent Studio filters strings
(new facetFiltersToFilterString / mergeFilters utilities)
Remove v3 version detection, webpack module aliases, ambient module
declarations, and the ensureAskAISupported guard
Refresh SearchTranslations for v5 labels

Breaking changes

Who does this affect: all sites using @docusaurus/theme-search-algolia
How to migrate:
- Replace indexName: 'x' with indices: ['x']
- Move any top-level searchParameters into the relevant index entry:
  indices: [{name: 'x', searchParameters: {...}}]
- Rename Ask AI assistantId → agentId
- Ensure @docsearch/react v5 is installed
Why make this breaking change: DocSearch v5 removes v3 APIs and adds
multi-index + Agent Studio Ask AI, which the old single-index config cannot express
Severity: high reach (every Algolia search user) × low-to-medium effort
(mostly a config rename)

// Before
algolia: {
  appId: '...',
  apiKey: '...',
  indexName: 'docusaurus-2',
  searchParameters: {facetFilters: ['language:en']},
  askAi: {assistantId: 'RgIMYFUmTfrN'},
}

// After
algolia: {
  appId: '...',
  apiKey: '...',
  indices: [{name: 'docusaurus-2', searchParameters: {facetFilters: ['language:en']}}],
  askAi: {agentId: 'RgIMYFUmTfrN'},
}

Bundle size

Configuration	Lazy modal chunk
Search only	~257.8 kB
Search + Ask AI	~554.7 kB

Note

There is an open issue to track removing the @base-ui/react dep from DocSearch here, which would reduce the overall bundles by ~51 kB.

Test Plan

pnpm --filter @docusaurus/theme-search-algolia build
pnpm test packages/docusaurus-theme-search-algolia
pnpm --filter @docusaurus/theme-translations run update (sync catalogs)
pnpm --filter website typecheck
pnpm build:website:fast and manually verify search + modal open/close

Test links

Deploy preview: https://deploy-preview-12406--docusaurus-2.netlify.app/

Related issues/PRs

Docs: migrate website/docs/search.mdx to indices / agentId / per-index params
Re-enable facets + contextual multi-value support once
@docsearch/react: Allow facets to have multiple selected values algolia/docsearch#3037 lands

…ndices config (AI-assisted) Upgrade @docsearch/react from v4 to v5 and drop the DocSearch v3 compatibility layer that was carried during the v3/v4 transition. Changes: - Bump @docsearch/react to ^5.0.4 and update the lockfile - Replace `algolia.indexName` + top-level `searchParameters` with an `algolia.indices` array (string or {name, searchParameters} entries) - Load the search vs. Ask AI modal via dedicated dynamic entry points - Migrate Ask AI to Agent Studio: `assistantId` -> `agentId`, per-index `searchParameters`, and add `memory` / `promptSuggestions` options - Convert contextual `facetFilters` into Agent Studio `filters` strings (new facetFiltersToFilterString / mergeFilters utils) - Remove v3 version detection, module aliases, ambient declarations, and the ensureAskAISupported guard - Refresh SearchTranslations for v5 labels and update tests - Migrate website dogfooding configs to `indices` and adjust DocSearch CSS BREAKING CHANGE: `algolia.indexName` and top-level `algolia.searchParameters` are removed in favor of `algolia.indices`. Ask AI now uses `agentId` instead of `assistantId`. DocSearch v3 is no longer supported. - Who does this affect: all sites using @docusaurus/theme-search-algolia - How to migrate: replace `indexName: 'x'` with `indices: ['x']`; move `searchParameters` into the relevant index entry; rename Ask AI `assistantId` to `agentId`; ensure `@docsearch/react` v5 is installed - Why make this breaking change: DocSearch v5 drops v3 APIs and introduces multi-index + Agent Studio Ask AI, which cannot be expressed with the old single-index config - Severity: high reach (every Algolia search user) x low-to-medium effort (mostly a config rename)

meta-cla · 2026-09-03T21:01:30Z

Hi @8bittitan!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

socket-security · 2026-09-03T21:02:31Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@docsearch/react@5.1.0

View full report

netlify · 2026-09-03T21:03:18Z

✅ [V2]

Name	Link
🔨 Latest commit	`d651ed5`
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/6aad71338586b600089f7a40
😎 Deploy Preview	https://deploy-preview-12406--docusaurus-2.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.

meta-cla · 2026-09-03T21:04:13Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

- Correct lint script typo lint:SPELLING -> lint:spelling - Fix "noisey" -> "noisy" typo in webpack warning comment - Add "askai" to project-words.txt and cSpell:ignore IMYF in config - Temporarily disable translation-consistency test (it.todo); translations are deferred to a follow-up PR to keep this PR small

argos-ci · 2026-09-18T14:03:18Z

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
screenshots (Inspect)	✅ No changes detected	-	Sep 18, 2026, 5:31 PM
text-snapshots (Inspect)	⚠️ Changes detected (Review)	1 changed	Sep 18, 2026, 5:31 PM

slorber

Here's a quick initial review

slorber · 2026-09-18T17:45:11Z

  it('merges [array,array]', () => {
    expect(mergeFacetFilters(['f1'], ['f2'])).toEqual(['f1', 'f2']);

    // TODO this looks wrong to me, should be [['f1', 'f2'], ['f3', 'f4']] ?


Any opinion on this TODO?

slorber · 2026-09-18T17:47:16Z

+  return facetFiltersToFilterStringInternal(facetFilters, 0) ?? '';
+}
+
+export function mergeFilters(


All this looks quite complex Algolia logic, why don't you expose a package to do that instead of us having to maintain it?

slorber · 2026-09-18T17:49:19Z

+    return existing;
+  }
+
+  return `(${existing}) AND (${added})`;


Why not support merging more than 2 filters?

Calling merge(merge(f1,f2),f3) is likely to create useless extra parentheses, no? Would this still work?

slorber · 2026-09-18T17:52:51Z

-  it('has base messages files contain EXACTLY all the translations extracted from the theme. Please run "pnpm --filter @docusaurus/theme-translations update" to keep base messages files up-to-date', async () => {
+  // TODO re-enable during https://github.com/8bittitan/docusaurus/pull/1 since
+  // these current changes left translations out for PR size.
+  it.todo('has base messages files contain EXACTLY all the translations extracted from the theme. Please run "pnpm --filter @docusaurus/theme-translations update" to keep base messages files up-to-date', async () => {


I see this PR mostly add new translations

Aren't there a lot of legacy v3 keys that are now unused? We should also remove them.

slorber · 2026-09-18T17:53:38Z

+        // TODO Enable once there is an Agent Studio agent to use
+        // askAi: {
+        // cSpell:ignore IMYF
+        //   agentId: 'RgIMYFUmTfrN',
+        //   suggestedQuestions: true,
+        // },


Why can't we use Ask AI anymore?

Will this be a problem for our users too?

slorber · 2026-09-18T17:55:38Z

+    | 'indices'
+    // TODO Enable once DocSearch releases fix for facets with multiple
+    // selected values. Currently the contextual search facets do no work.
+    // https://github.com/algolia/docsearch/issues/3037


Looks merged/fixed now?

slorber · 2026-09-18T17:56:16Z

-      }
-      return undefined;
+      return {
+        ignoreWarnings: [


what's this for? problem still there after ai sdk v6 upgrade?

slorber · 2026-09-18T17:58:23Z

+  // The algoliasearch-helper only allows for a single index, here we just treat
+  // the FIRST index in the `indices` list as the "primary" index
+  const indexName = getIndexName(indices);
+
+  if (!indexName) {
+    throw new Error(
+      `Could not find a useable index in "algolia.indices" for the SearchPage.
+       Ensure you've added the correct index names in order for search to work.
+      `,
+    );
+  }


looks like a limitation, maybe we'll have to document this?

I still don't know what's the reason to use multiple indices, and how this can be a probelm for us.

Do you expect many Docusaurus users to use multiple indices and encouter this limitation?

meta-cla Bot added the CLA Signed Signed Facebook CLA label Sep 3, 2026

8bittitan and others added 2 commits September 4, 2026 12:37

Merge branch 'main' into feat/docsearch-upgrade-v5

4e18304

8bittitan marked this pull request as ready for review September 4, 2026 17:35

8bittitan requested review from Josh-Cena and slorber as code owners September 4, 2026 17:35

slorber added the Argos Add this label to run UI visual regression tests. See argos.yml GH action. label Sep 18, 2026

Merge main into feat/docsearch-upgrade-v5 (AI-assisted)

c7151ec

slorber added 2 commits September 18, 2026 17:55

Merge latest main into feat/docsearch-upgrade-v5 (AI-assisted)

2a220ec

Merge main with Node 24 restoration (AI-assisted)

d651ed5

slorber added the pr: breaking change Existing sites may not build successfully in the new version. Description contains more details. label Sep 18, 2026

slorber changed the title ~~feat(theme-search-algolia)!: upgrade to DocSearch v5 (AI-assisted)~~ break(theme-search-algolia)!: upgrade to DocSearch v5 (AI-assisted) Sep 18, 2026

slorber reviewed Sep 18, 2026

View reviewed changes

Uh oh!

Conversation

8bittitan commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

What changed

Breaking changes

Bundle size

Test Plan

Test links

Related issues/PRs

Uh oh!

meta-cla Bot commented Sep 3, 2026

Action Required

Process

Uh oh!

socket-security Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ [V2]

Uh oh!

meta-cla Bot commented Sep 3, 2026

Uh oh!

argos-ci Bot commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slorber left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

8bittitan commented Sep 3, 2026 •

edited

Loading

socket-security Bot commented Sep 3, 2026 •

edited

Loading

netlify Bot commented Sep 3, 2026 •

edited

Loading

argos-ci Bot commented Sep 18, 2026 •

edited

Loading