feat(search): add runtime support for DocSearch v4 #11327

dylantientcheu · 2025-07-15T10:28:44Z

IMPORTANT

@slorber: This PR adds runtime support for DocSearch v4, but does not upgrade to DocSearch v4.

If you want to use DocSearch v4, make sure to read this comment: #11327 (review)

And check this follow-up PR: #11421

Motivation

10 years of DocSearch!
It’s been a decade since DocSearch was launched, empowering millions of developers to find documentation faster and more intuitively.
5 years since DocSearch v3:
After half a decade of feedback and innovation, we’re excited to unveil the next major leap.
This PR updates DocSearch to its latest version (v4) and introduces the Ask AI feature, reflecting our vision for the next generation of documentation search. Our goal is to provide a more powerful, accessible, and intelligent search experience for your users.
Ask AI is completely optional and never enabled by default. DocSearch v4 can be used independently of Ask AI, giving you full control over your integration.
- Interested in trying Ask AI? Sign up for our private beta here: Google Form link
- See the full list of supported providers/models for Ask AI.
- Read more in the DocSearch v4 documentation and Ask AI documentation.

What is included in this PR

Upgraded the version of docsearch to use the latest beta
Added the new askAi prop
Added the new translation keys for docsearch
Updated the Algolia logo on the contextual search page
Update Algolia Search documentation section.

Test Plan

Try the new search experience by clicking the search button or using the keyboard shortcut (Cmd + K or Ctrl + K).

Features

DocSearch v4

Completely modernized UI: DocSearch v4 features a brand new, ground-up redesign for a more intuitive and visually appealing experience.
Still 💯 Free: DocSearch stays free for all eligible documentation/technical blog websites as it has always been.
Core functionality preserved: All the features users love from previous versions remain, ensuring a seamless transition.
Customization-first: Extensive customization options remain at the heart of DocSearch, allowing you to tailor the look and feel to your brand.
Recent searches & favorites: Continue to quickly revisit previous keyword searches and save favorites for easy access.
Enhanced accessibility and performance: Improved ARIA support, keyboard navigation, and even faster load times.
Mobile-optimized: Responsive and touch-friendly for a great experience on any device.
Dark mode: Seamless integration with your site’s dark theme.

Ask AI

Conversational search: Users can ask questions in natural language and get context-aware answers.
Completely free: Ask AI is available at no additional cost.
BYOLLM (Bring Your Own LLM): You can use your own language model provider, giving you full control over the AI experience.
Direct Algolia index integration: The provider/models retrieve relevant context directly from your Algolia index, ensuring accurate and up-to-date answers.
Recently asked & conversation history: Easily revisit your recent questions and jump back into previous Ask AI conversations.
Seamless integration: Ask AI is available directly from the search modal.

References

netlify · 2025-07-15T10:31:08Z

✅ [V2]

Name	Link
🔨 Latest commit	`8fe7dfc`
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/68cd43251dcc9f0008bf9c8f
😎 Deploy Preview	https://deploy-preview-11327--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

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

github-actions · 2025-07-15T10:33:59Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🔴 40	🟢 98	🟢 100	🟢 100	Report
/docs/installation	🟠 50	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 69	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 58	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 60	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 61	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 69	🟢 100	🟢 100	🟠 86	Report

socket-security · 2025-07-22T14:43:00Z

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

…heu/docusaurus into algolia/docsearch-v4

slorber

Thanks for the PR

I'm ok to help dogfood DocSearch v4 on Docusaurus v3.x, because it looks mostly retrocompatible in terms of API, and probably not too disruptive in terms of UX

But:

DocSearch v4 is still in beta, and I'm seeing it being still actively worked on. We can't prevent our users from upgrading to the latest Docusaurus v3.x release due to changes you make that affect us. It would be preferable to either wait for your GA release, or to keep retrocompatibility with DocSearch v3 and let users upgrade on their own term (we can eventually let newly initialized Docusaurus sites use DocSearch v4 by default)
Do you guarantee that there will be no more breaking change in DocSearch v4 that could annoy Docusaurus users if they upgrade their dependencies in the future?
There are a few things like labels and disruptive design changes that are currently not retro-compatible, making it difficult to merge this for Docusaurus v3 because this would force Docusaurus v3 users to upgrade DocSearch if they upgrade to our latest v3. I want to derisk and let users choose.

To me, the most disruptive design/UX change you include in DocSearch v4 is the larger search bar button. If we merge this PR as is, this is going to affect many sites upgrading to the latest Docusaurus v3.x release, in particular the layout of the navbar.

For example, the React Native website would have its title elipsed for some screen sizes, and that doesn't look good.

Many Docusaurus sites have crowded navbars where labels and items have been optimized to avoid that. We don't want all these sites to have to write custom CSS if they upgrade to our latest minor release.

Including us, cf what reports our visual regression testing tool doesn't look good for the default viewport size:

#11327 (comment)

Considering the placeholder remains "Search" (and I'm not sure we want to change it, even for Docusauus v4), I see no reason to have such a large search bar button, and would prefer to revert to the DocSearch v3 size.

In general, we advertise our minor version releases to be seamless upgrades. Some users upgrade without even looking at our release notes, that should not contain any migration instructions.

The design changes coming with DocSearch v4 are significant enough to disrupt existing sites, that may inadvertently ship DocSearch v4 to production without knowing, and then being disappointed that their CSS customizations and theming doesn't look that good. We want to avoid that, that's why I'd prefer to keep DocSearch v3 retrocompatibility. Or we'll have to wait for Docusaurus v4.

packages/docusaurus-theme-search-algolia/package.json

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx

website/docs/search.mdx

website/docusaurus.config.ts

argos-ci · 2025-07-25T11:22:55Z

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	252 changed	Sep 19, 2025, 11:58 AM

dylantientcheu · 2025-07-29T16:59:17Z

Thanks for the detailed feedback 🙏

TLDR: this PR no longer forces anyone onto DocSearch v4, keeps the v3 look-and-feel, and gates every v4-only feature behind a version check. Docusaurus v3 users can safely upgrade.

What changed since your review

Version range – @docsearch/react is now "^3.9.0 || ^4.0.0-beta.5 || ^4.0.0". Existing sites keep v3 by default; v4 is opt-in.
Conditional code paths – we detect version.major === 4 once and only wire Ask AI / modal tweaks when that’s true. On v3 everything behaves exactly as before.
Search-bar size – reverted to the v3 dimensions; We are also updating the base package to revert this change.
Translations – new keys are additive; v3 instances ignore them.

On future breaking changes

I can’t promise we will never tweak the v4 beta–we are still working on some accessibility fixes, but:

I can promise that we will NOT change the keyword search (neither the API nor the UX)
AskAI will probably morph a bit while we work towards GA.
We’ve pinned the exact beta we support (4.0.0-beta.5) so downstream installs are stable.
If/when DocSearch ships a GA with breaking UI we’ll hold off bumping the range until we’ve tested it against Docusaurus v3 & v4.
Worst-case, users stay on the proven v3 line—always within the semver range above–until docusaurus v4 release.

Happy to tweak anything else you’d like, but I think this addresses the retrofit + UX concerns you raised.

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx

website/docs/search.mdx

yarn.lock

packages/docusaurus-theme-search-algolia/src/theme/SearchTranslations/index.ts

dylantientcheu · 2025-08-11T09:07:47Z

Thanks again for the review.

All relevant fixes are in this commit: b7c60c5 (#11327)

slorber · 2025-09-16T10:42:59Z

Thanks, it seems to work.

Just want to report a few issues:

You broke types between beta.8 and GA (indexName becoming optional requires fixes on our side). It's better to only release GA/RC once all these changes have already been made
Docusaurus is not going to immediately support all the DocSearch v4 features. This will need another PR to ensure that we properly accept the indices config in a retrocompatible way, and merge contextual search param filters into indices.searchParameters. I guess we can add support for that in Docusaurus v4 once we can drop support for DocSearch v3, it will be easier to not have to deal with retro-compatibility.
There's likely a missing dependency on Zod, reported here: DocSearch v4 - missing Zod peerDependency algolia/docsearch#2758

This won't block the current PR, though, and I'll merge the PR asap.

slorber · 2025-09-16T10:49:58Z

Hmmm, no, doesn't work yet 😅:

Search now crashes at runtime: https://deploy-preview-11327--docusaurus-2.netlify.app/ - Problem reported here: feat(v4): Add support for multi-index search algolia/docsearch#2736 (review)
The AI SDK upgrade now requires a newer TS version to support NoInfer. Unfortunately, our CI ensures our website still typechecks with lower version TS 5.1, and NoInfer was added later. This is not a problem for you since the DocSearch v4 upgrade is optional, so not a breaking change. But it is for me since I need to find a decent workaround for our CI.

8bittitan · 2025-09-16T11:40:28Z

You broke types between beta.8 and GA (indexName becoming optional requires fixes on our side). It's better to only release GA/RC once all these changes have already been made

Sorry about that! We wanted to keep it backwards compatible and just mark it as deprecated for a case such as this 😅

8bittitan · 2025-09-16T13:50:49Z

@slorber The indexName issues should be fixed from this PR. It moves the backwards compatibility check to within the <DocSearchModal /> component.

slorber · 2025-09-16T14:23:11Z

Thanks!

There's also something else that our CI caught (unfortunately, it can't post a comment on external PRs but can be seen on this job)

Upgrading Algolia to support AskAI makes our main bundle 325 kb heavier (minimized and tree-shaken), that's a lot just for this feature:

We are importing the modal with dynamic imports: import('@docsearch/react/modal'). This normally makes it possible to code-split the modal code into a separate JS chunk, but it looks to me that now, heavy dependencies end up in our main bundle (likely the AI SDK).

Can you check your dependency graph to ensure this doesn't happen?

It's a bit annoying for us if users upgrade to DocSearch v4 and their site becomes +39% heavier. Since this is the main bundle, this will also delay React hydration and lower the Lighthouse scores. I'm fine if the heavy things are lazy loaded on button hover/click, but paying the cost upfront is a bit too much 😅, and it will be the case even if users don't enable AskAI.

dylantientcheu · 2025-09-16T15:15:03Z

Thanks for the flag @slorber

Optimization is on our roadmap. We'll work towards that too.

We just released v4.0.1 which should fix all the issues you mentioned in the previous comment.

8bittitan · 2025-09-16T16:48:54Z

@slorber I have an open PR up that extends the exports like you mentioned above. Would love if you could take a peek and see if that's what you had in mind; at least while we tackle solving the bundling/splitting more aggressively!

slorber

The PR is ready to merge 🥳

However there's a twist

Due to a 300+kb main bundle size increase, we are going to support DocSearch v4 at runtime, but won't use DocSearch v4 by default until that issue is solved.

The cost is too high, and it affects sites that do not even use the new Ask AI feature.

For that reason, and until it is fixed, those willing to use DocSearch v4 on their site will need to use a package manager resolution config:

npm overrides:

{
  "overrides": {
    "@docsearch/react": "^4.0.0"
  }
}

Yarn v1 resolutions

{
  "resolutions": {
    "@docsearch/react": "^4.0.0"
  }
}

Other package managers may provide similar package resolution features (for example: pnpm overrides overrides) and Yarn v2+ CLI)

Docusaurus v3 will be compatible with both DocSearch v3/v4.

We are also going to run DocSearch v4 on our production website docusaurus.io, to dogfood the new DocSearch / Ask AI feature, and ensure the compatibility does not break.

Should you use DocSearch v4?

If you want to use DocSearch v4 / Ask AI now, you can with an opt-in bundler config, but keep in mind this will increase your main bundle size and potentially slow down the initial load time and React hydration time on all pages of your site.

If you don't plan to use Ask AI, we recommend continuing to use DocSearch v3, and not paying the bundle size increase cost.

In the future, we should be able to optimize that so that the 300+kb are code-split to a separate lazy-loaded bundle. Read the upcoming v3.9 blog post to know what the final tradeoff will be when this feature appears in a stable version of Docusaurus.

Edit: the optimization will be ready for Docusaurus v3.9, see follow-up PR here: #11421

slorber · 2025-09-23T10:34:08Z

The bundle size issue should be fixed in #11421

feat(search): update Docsearch to v4-beta

2d1d9c9

dylantientcheu requested review from Josh-Cena and slorber as code owners July 15, 2025 10:28

meta-cla bot added the CLA Signed Signed Facebook CLA label Jul 15, 2025

dylantientcheu added 4 commits July 15, 2025 13:06

fix: update search docs

a990dfd

fix: checks

9a72c17

fix: replace search by, by powered by

4752b94

fix(askai): add facet filters

0233bda

dylantientcheu added 3 commits July 22, 2025 20:26

Merge branch 'main' into algolia/docsearch-v4

8766d31

fix: factor out string typecheck

e771fb1

Merge branch 'algolia/docsearch-v4' of https://github.com/dylantientc…

53ff498

…heu/docusaurus into algolia/docsearch-v4

slorber added pr: new feature This PR adds a new API or behavior. Argos Add this label to run UI visual regression tests. See argos.yml GH action. labels Jul 25, 2025

slorber requested changes Jul 25, 2025

View reviewed changes

fix: based on comments

4fed7f0

dylantientcheu requested a review from slorber July 29, 2025 17:08

This was referenced Aug 6, 2025

Replace Chef AI's "Ask Sablier" with "Ask in ChatGPT" sablier-labs/docs#341

Closed

feat: integrate docsearch v4 beta with ask ai sablier-labs/docs#342

Merged

slorber requested changes Aug 8, 2025

View reviewed changes

slorber marked this pull request as draft August 8, 2025 14:26

dylantientcheu requested a review from slorber August 11, 2025 09:07

fixup: resolve comments

b7c60c5

dylantientcheu force-pushed the algolia/docsearch-v4 branch from 099d1b4 to b7c60c5 Compare August 11, 2025 09:11

fix: version range

6b2aa00

slorber added 2 commits September 16, 2025 11:48

Merge branch 'main' into algolia/docsearch-v4

b6521ea

upgrade Zod to fix website typechecking issue

b82fa25

try to fix TS skipLibCheck=false problem for TS 5.1 CI

b3ce80b

slorber mentioned this pull request Sep 16, 2025

feat(v4): Add support for multi-index search algolia/docsearch#2736

Merged

1 task

try to fix DocSearch problem with TS 5.1 CI checks

1e1053b

empty

1d23aee

This comment was marked as spam.

Sign in to view

Upgrade to 4.0.1

3920ce1

slorber mentioned this pull request Sep 19, 2025

feat(faster): upgrade Rspack to 1.5, use lazyBarrel experiment, remove deprecated option #11415

Merged

slorber added 6 commits September 19, 2025 12:20

Merge branch 'main' into algolia/docsearch-v4

f56e21c

try to fix CI issue

f2895d6

try to fix CI issue

cb60bab

try to fix the CI issues

8957643

revert to DocSearch v3 by default (for now)

9efee55

lockfile

8fe7dfc

slorber approved these changes Sep 19, 2025

View reviewed changes

slorber changed the title ~~feat(search): update Docsearch to v4-beta~~ feat(search): add runtime support for DocSearch v4 Sep 19, 2025

slorber merged commit 9c68988 into facebook:main Sep 19, 2025
40 of 43 checks passed

dylantientcheu mentioned this pull request Sep 19, 2025

fix: add docsearch 4 to website algolia/docsearch#2767

Merged

This was referenced Sep 23, 2025

feat(theme-search-algolia): use DocSearch v4.1, optimize integration #11421

Merged

Runaway bundle sizes algolia/docsearch#2769

Open

Uh oh!

feat(search): add runtime support for DocSearch v4 #11327

feat(search): add runtime support for DocSearch v4 #11327

Uh oh!

Conversation

dylantientcheu commented Jul 15, 2025 • edited by slorber Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

IMPORTANT

Motivation

What is included in this PR

Test Plan

Features

DocSearch v4

Ask AI

References

Uh oh!

netlify bot commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ [V2]

Uh oh!

github-actions bot commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚡️ Lighthouse report for the deploy preview of this PR

Uh oh!

socket-security bot commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slorber left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

argos-ci bot commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dylantientcheu commented Jul 29, 2025

What changed since your review

On future breaking changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dylantientcheu commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

slorber commented Sep 16, 2025

Uh oh!

slorber commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

8bittitan commented Sep 16, 2025

Uh oh!

8bittitan commented Sep 16, 2025

Uh oh!

slorber commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dylantientcheu commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as spam.

8bittitan commented Sep 16, 2025

Uh oh!

This comment was marked as spam.

slorber left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

dylantientcheu commented Jul 15, 2025 •

edited by slorber

Loading

netlify bot commented Jul 15, 2025 •

edited

Loading

github-actions bot commented Jul 15, 2025 •

edited

Loading

socket-security bot commented Jul 22, 2025 •

edited

Loading

slorber left a comment •

edited

Loading

argos-ci bot commented Jul 25, 2025 •

edited

Loading

dylantientcheu commented Aug 11, 2025 •

edited

Loading

slorber commented Sep 16, 2025 •

edited

Loading

slorber commented Sep 16, 2025 •

edited

Loading

dylantientcheu commented Sep 16, 2025 •

edited

Loading

slorber left a comment •

edited

Loading