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

Co-authored-by: slorber <749374+slorber@users.noreply.github.com>

Author: slorber

package.json

@@ -129,8 +129,5 @@
     "stylelint-config-standard": "^29.0.0",
     "typescript": "~5.8.2"
   },
-  "resolutions": {
-    "@docsearch/react": "^4.0.1"
-  },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

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

@@ -33,7 +33,7 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docsearch/react": "^3.9.0",
+    "@docsearch/react": "^3.9.0 || ^4.1.0",
     "@docusaurus/core": "3.8.1",
     "@docusaurus/logger": "3.8.1",
     "@docusaurus/plugin-content-docs": "3.8.1",

packages/docusaurus-theme-search-algolia/src/client/useAlgoliaAskAi.ts

@@ -6,15 +6,15 @@
  */
 
 import {useCallback, useMemo, useState} from 'react';
-import {
-  version as docsearchVersion,
-  type DocSearchModalProps,
-  type DocSearchTranslations,
-} from '@docsearch/react';
+import {version as docsearchVersion} from '@docsearch/react/version';
 import translations from '@theme/SearchTranslations';
 import {useAlgoliaContextualFacetFiltersIfEnabled} from './useAlgoliaContextualFacetFilters';
 import {mergeFacetFilters} from './utils';
 import type {AskAiConfig} from '@docusaurus/theme-search-algolia';
+import type {
+  DocSearchModalProps,
+  DocSearchTranslations,
+} from '@docsearch/react';
 import type {FacetFilters} from 'algoliasearch/lite';
 
 // The minimal props the hook needs from DocSearch v4 props

packages/docusaurus-theme-search-algolia/src/docSearchVersion.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {version as docSearchVersion} from '@docsearch/react';
+
+// TODO Docusaurus v4: upgrade to DocSearch v4
+//  drop v3 compat, remove this file?
+export const docSearchV3: boolean = docSearchVersion.startsWith('3.');

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

@@ -12,6 +12,7 @@ import {
   createOpenSearchHeadTags,
   shouldCreateOpenSearchFile,
 } from './opensearch';
+import {docSearchV3} from './docSearchVersion';
 
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
@@ -65,6 +66,26 @@ export default function themeSearchAlgolia(context: LoadContext): Plugin<void> {
       }
       return {};
     },
+
+    configureWebpack() {
+      // TODO Docusaurus v4: remove after dropping DocSearch v3 support
+      if (docSearchV3) {
+        // These aliases ensure DocSearch v3 imports are compatible with
+        // the newly added DocSearch v4 entry points
+        // See https://github.com/algolia/docsearch/pull/2764
+        const docSearchV3Entry = require.resolve('@docsearch/react');
+        return {
+          resolve: {
+            alias: {
+              '@docsearch/react/version': docSearchV3Entry,
+              '@docsearch/react/useDocSearchKeyboardEvents': docSearchV3Entry,
+              '@docsearch/react/useTheme': docSearchV3Entry,
+            },
+          },
+        };
+      }
+      return undefined;
+    },
   };
 }
 

packages/docusaurus-theme-search-algolia/src/theme-search-algolia.d.ts

@@ -5,6 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// TODO Docusaurus v4: remove after we drop support for DocSearch v3
+declare module '@docsearch/react/button';
+declare module '@docsearch/react/useDocSearchKeyboardEvents';
+declare module '@docsearch/react/version';
+
 declare module '@docusaurus/theme-search-algolia' {
   import type {DeepPartial, Overwrite} from 'utility-types';
 

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

@@ -13,7 +13,8 @@ import React, {
   type ReactNode,
 } from 'react';
 import {createPortal} from 'react-dom';
-import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
+import {DocSearchButton} from '@docsearch/react/button';
+import {useDocSearchKeyboardEvents} from '@docsearch/react/useDocSearchKeyboardEvents';
 import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
 import {useHistory} from '@docusaurus/router';
@@ -73,9 +74,7 @@ function importDocSearchModalIfNeeded() {
     return Promise.resolve();
   }
   return Promise.all([
-    import('@docsearch/react/modal') as Promise<
-      typeof import('@docsearch/react')
-    >,
+    import('@docsearch/react/modal'),
     import('@docsearch/react/style'),
     import('./styles.css'),
   ]).then(([{DocSearchModal: Modal}]) => {

packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts

@@ -7,7 +7,7 @@
 
 import {escapeRegexp} from '@docusaurus/utils';
 import {Joi} from '@docusaurus/utils-validation';
-import {version as docsearchVersion} from '@docsearch/react';
+import {docSearchV3} from './docSearchVersion';
 import type {ThemeConfigValidationContext} from '@docusaurus/types';
 import type {
   ThemeConfig,
@@ -123,9 +123,10 @@ export const Schema = Joi.object<ThemeConfig>({
     .unknown(),
 });
 
+// TODO Docusaurus v4: remove this check when we drop DocSearch v3
 function ensureAskAISupported(themeConfig: ThemeConfig) {
   // enforce DocsSearch v4 requirement when AskAI is configured
-  if (themeConfig.algolia.askAi && !docsearchVersion.startsWith('4.')) {
+  if (themeConfig.algolia.askAi && docSearchV3) {
     throw new Error(
       'The askAi feature is only supported in DocSearch v4. ' +
         'Please upgrade to DocSearch v4 by installing "@docsearch/react": "^4.0.0" ' +

website/docusaurus.config.ts

@@ -656,7 +656,8 @@ export default async function createConfigAsync() {
         apiKey: 'bf7211c161e8205da2f933a02534105a',
         indexName: 'docusaurus-2',
 
-        // TODO temporary, for DocSearch v3/v4 conditional Ask AI integration
+        // TODO Docusaurus v4: remove after we drop DocSearch v3
+        //  temporary, for DocSearch v3/v4 conditional Ask AI integration
         //  see https://github.com/facebook/docusaurus/pull/11327
         // eslint-disable-next-line @typescript-eslint/no-var-requires,global-require
         ...(require('@docsearch/react').version.startsWith('4.')