Core: concentrate search API utils

fuma-nama · fuma-nama · commit d1ae3e8b8732 · 2025-09-21T16:59:17.000+08:00
diff --git a/.changeset/light-pants-pump.md b/.changeset/light-pants-pump.md
@@ -0,0 +1,9 @@
+---
+'fumadocs-core': minor
+---
+
+**Move `SortedResult` and other search-related types to `fumadocs-core/search`**
+
+This also exposed the search result highlighter API, you may now use it for highlighting results of your own search integration
+
+Old export will be kept until the next major release.
diff --git a/apps/docs/content/docs/headless/props.ts b/apps/docs/content/docs/headless/props.ts
@@ -1,11 +1,12 @@
 import type * as Breadcrumb from 'fumadocs-core/breadcrumb';
 import type * as TOC from 'fumadocs-core/toc';
 import type * as Server from 'fumadocs-core/server';
+import type * as Search from 'fumadocs-core/search';
 import type * as Sidebar from 'fumadocs-core/sidebar';
 import type { ElementType } from 'react';
 import type * as MDX from 'fumadocs-core/mdx-plugins';
 
-export type SortedResult = Server.SortedResult;
+export type SortedResult = Search.SortedResult;
 
 export type StructureOptions = MDX.StructureOptions;
 
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -32,6 +32,10 @@
       "import": "./dist/hide-if-empty.js",
       "types": "./dist/hide-if-empty.d.ts"
     },
+    "./search": {
+      "import": "./dist/search/index.js",
+      "types": "./dist/search/index.d.ts"
+    },
     "./search/*": {
       "import": "./dist/search/*.js",
       "types": "./dist/search/*.d.ts"
diff --git a/packages/core/src/search/client.ts b/packages/core/src/search/client.ts
@@ -6,7 +6,7 @@ import { type StaticOptions } from '@/search/client/static';
 import { type AlgoliaOptions } from '@/search/client/algolia';
 import { type OramaCloudOptions } from '@/search/client/orama-cloud';
 import { type MixedbreadOptions } from '@/search/client/mixedbread';
-import type { SortedResult } from '@/search/shared';
+import type { SortedResult } from '@/search';
 
 interface UseDocsSearch {
   search: string;
diff --git a/packages/core/src/search/client/algolia.ts b/packages/core/src/search/client/algolia.ts
@@ -1,6 +1,6 @@
 import type { BaseIndex } from '@/search/algolia';
 import type { Hit, LiteClient, SearchResponse } from 'algoliasearch/lite';
-import { createContentHighlighter, type SortedResult } from '@/search/shared';
+import { createContentHighlighter, type SortedResult } from '@/search';
 
 export interface AlgoliaOptions {
   indexName: string;
diff --git a/packages/core/src/search/client/fetch.ts b/packages/core/src/search/client/fetch.ts
@@ -1,4 +1,4 @@
-import type { SortedResult } from '@/server';
+import type { SortedResult } from '@/search';
 
 export interface FetchOptions {
   /**
diff --git a/packages/core/src/search/client/mixedbread.ts b/packages/core/src/search/client/mixedbread.ts
@@ -1,4 +1,4 @@
-import { SortedResult } from '@/server';
+import type { SortedResult } from '@/search';
 import Mixedbread from '@mixedbread/sdk';
 import { VectorStoreSearchResponse } from '@mixedbread/sdk/resources/vector-stores';
 import removeMd from 'remove-markdown';
diff --git a/packages/core/src/search/client/orama-cloud.ts b/packages/core/src/search/client/orama-cloud.ts
@@ -1,8 +1,7 @@
-import type { SortedResult } from '@/server';
 import type { ClientSearchParams, OramaClient } from '@oramacloud/client';
 import { removeUndefined } from '@/utils/remove-undefined';
 import type { OramaIndex } from '@/search/orama-cloud';
-import { createContentHighlighter } from '@/search/shared';
+import { createContentHighlighter, type SortedResult } from '@/search';
 
 interface CrawlerIndex {
   path: string;
diff --git a/packages/core/src/search/index.ts b/packages/core/src/search/index.ts
@@ -1,18 +1,27 @@
-export interface SortedResult {
+import type { ReactNode } from 'react';
+
+export interface SortedResult<Content = string> {
   id: string;
   url: string;
   type: 'page' | 'heading' | 'text';
-  content: string;
-  contentWithHighlights?: HighlightedText[];
+  content: Content;
+
+  /**
+   * breadcrumbs to be displayed on UI
+   */
+  breadcrumbs?: Content[];
+  contentWithHighlights?: HighlightedText<Content>[];
 }
 
-export type HighlightedText = {
+export type ReactSortedResult = SortedResult<ReactNode>;
+
+export interface HighlightedText<Content = string> {
   type: 'text';
-  content: string;
+  content: Content;
   styles?: {
     highlight?: boolean;
   };
-};
+}
 
 function escapeRegExp(input: string): string {
   return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
diff --git a/packages/core/src/search/orama/search/advanced.ts b/packages/core/src/search/orama/search/advanced.ts
@@ -4,8 +4,7 @@ import {
   type advancedSchema,
 } from '@/search/orama/create-db';
 import { removeUndefined } from '@/utils/remove-undefined';
-import type { SortedResult } from '@/server';
-import { createContentHighlighter } from '@/search/shared';
+import { createContentHighlighter, type SortedResult } from '@/search';
 
 export async function searchAdvanced(
   db: Orama<typeof advancedSchema>,
diff --git a/packages/core/src/search/orama/search/simple.ts b/packages/core/src/search/orama/search/simple.ts
@@ -1,10 +1,9 @@
 import { type Orama, search, type SearchParams } from '@orama/orama';
-import type { SortedResult } from '@/server';
 import {
   type SimpleDocument,
   type simpleSchema,
 } from '@/search/orama/create-db';
-import { createContentHighlighter } from '@/search/shared';
+import { createContentHighlighter, type SortedResult } from '@/search';
 
 export async function searchSimple(
   db: Orama<typeof simpleSchema>,
diff --git a/packages/core/src/search/server.ts b/packages/core/src/search/server.ts
@@ -17,7 +17,7 @@ import {
 } from '@/search/orama/create-db';
 import { searchSimple } from '@/search/orama/search/simple';
 import { searchAdvanced } from '@/search/orama/search/advanced';
-import type { SortedResult } from '@/search/shared';
+import type { SortedResult } from '@/search';
 
 type SearchType = 'simple' | 'advanced';
 
@@ -181,4 +181,4 @@ export function initAdvancedSearch(options: AdvancedOptions): SearchServer {
 
 export { createFromSource } from './orama/create-from-source';
 export { createI18nSearchAPI } from './orama/create-i18n';
-export * from './shared';
+export * from './index';
diff --git a/packages/core/src/server/index.ts b/packages/core/src/server/index.ts
@@ -4,5 +4,5 @@ export * as PageTree from '../source/page-tree/definitions';
 export * from './git-api';
 export * from './metadata';
 
-// backward compat
-export type { SortedResult } from '../search/shared';
+// TODO: replace this with `fumadocs-core/search`
+export type { SortedResult } from '../search';
diff --git a/packages/core/test/highlight.test.ts b/packages/core/test/highlight.test.ts
@@ -1,5 +1,5 @@
 import { expect, test } from 'vitest';
-import { createContentHighlighter } from '@/search/shared';
+import { createContentHighlighter } from '@/search';
 
 test('highlight search results', () => {
   const highlighter = createContentHighlighter('hello world helloworld');
diff --git a/packages/core/tsup.config.ts b/packages/core/tsup.config.ts
@@ -12,10 +12,7 @@ export default defineConfig({
   entry: [
     'src/{toc,link,breadcrumb,sidebar,dynamic-link,hide-if-empty}.tsx',
     'src/{server,source,mdx-plugins,content}/index.ts',
-    'src/search/client.ts',
-    'src/search/server.ts',
-    'src/search/algolia.ts',
-    'src/search/orama-cloud.ts',
+    'src/search/{index,client,server,algolia,orama-cloud}.ts',
     'src/utils/use-on-change.ts',
     'src/utils/use-effect-event.ts',
     'src/utils/use-media-query.ts',
diff --git a/packages/ui/src/components/dialog/search-algolia.tsx b/packages/ui/src/components/dialog/search-algolia.tsx
@@ -16,11 +16,11 @@ import {
   SearchDialogInput,
   SearchDialogList,
   SearchDialogOverlay,
+  type SharedProps,
   TagsList,
   TagsListItem,
-  type SharedProps,
 } from './search';
-import type { SortedResult } from 'fumadocs-core/server';
+import type { SortedResult } from 'fumadocs-core/search';
 import type { SearchLink, TagItem } from '@/contexts/search';
 import { useI18n } from '@/contexts/i18n';
 
diff --git a/packages/ui/src/components/dialog/search-default.tsx b/packages/ui/src/components/dialog/search-default.tsx
@@ -14,11 +14,11 @@ import {
   SearchDialogInput,
   SearchDialogList,
   SearchDialogOverlay,
+  type SharedProps,
   TagsList,
   TagsListItem,
-  type SharedProps,
 } from './search';
-import type { SortedResult } from 'fumadocs-core/server';
+import type { SortedResult } from 'fumadocs-core/search';
 import type { SearchLink, TagItem } from '@/contexts/search';
 
 export interface DefaultSearchDialogProps extends SharedProps {
diff --git a/packages/ui/src/components/dialog/search-orama.tsx b/packages/ui/src/components/dialog/search-orama.tsx
@@ -16,11 +16,11 @@ import {
   SearchDialogInput,
   SearchDialogList,
   SearchDialogOverlay,
+  type SharedProps,
   TagsList,
   TagsListItem,
-  type SharedProps,
 } from './search';
-import type { SortedResult } from 'fumadocs-core/server';
+import type { SortedResult } from 'fumadocs-core/search';
 import type { SearchLink, TagItem } from '@/contexts/search';
 import { useI18n } from '@/contexts/i18n';
 
diff --git a/packages/ui/src/components/dialog/search.tsx b/packages/ui/src/components/dialog/search.tsx
@@ -21,20 +21,21 @@ import {
   DialogOverlay,
   DialogTitle,
 } from '@radix-ui/react-dialog';
-import type { SortedResult } from 'fumadocs-core/server';
+import type {
+  HighlightedText,
+  ReactSortedResult as BaseResultType,
+} from 'fumadocs-core/search';
 import { cva } from 'class-variance-authority';
 import { useEffectEvent } from 'fumadocs-core/utils/use-effect-event';
 import { useRouter } from 'fumadocs-core/framework';
 import type { SharedProps } from '@/contexts/search';
 import { useOnChange } from 'fumadocs-core/utils/use-on-change';
 import scrollIntoView from 'scroll-into-view-if-needed';
 import { buttonVariants } from '@/components/ui/button';
-import type { HighlightedText } from 'fumadocs-core/search/server';
 
-type ReactSortedResult = Omit<SortedResult, 'content'> & {
+interface ReactSortedResult extends BaseResultType {
   external?: boolean;
-  content: ReactNode;
-};
+}
 
 // needed for backward compatible since some previous guides referenced it
 export type { SharedProps };
@@ -469,7 +470,7 @@ export function TagsListItem({
   );
 }
 
-function renderHighlights(highlights: HighlightedText[]): ReactNode {
+function renderHighlights(highlights: HighlightedText<ReactNode>[]): ReactNode {
   return highlights.map((node, i) => {
     if (node.styles?.highlight) {
       return (

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { SortedResult } from '@/server';`
	`1`	`+import type { SortedResult } from '@/search';`
`2`	`2`
`3`	`3`	`export interface FetchOptions {`
`4`	`4`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { SortedResult } from '@/server';`
	`1`	`+import type { SortedResult } from '@/search';`
`2`	`2`	`import Mixedbread from '@mixedbread/sdk';`
`3`	`3`	`import { VectorStoreSearchResponse } from '@mixedbread/sdk/resources/vector-stores';`
`4`	`4`	`import removeMd from 'remove-markdown';`