---
title: "Orama Integration"
description: "Orama Integration within the Fumadocs ecosystem provides a sophisticated, type-safe approach to full-text search. By leveraging Orama's high-performance search engine (both via Orama Cloud or stati..."
last_updated: "2026-07-02T09:46:39.007434+00:00"
canonical_url: "https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/search-subsystem/orama-integration"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [packages/core/src/search/client.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client.ts)
- [packages/create-app/src/plugins/orama-cloud.ts](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/plugins/orama-cloud.ts)
- [packages/core/src/search/orama/create-server.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/create-server.ts)
- [packages/core/src/search/client/orama-static.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/orama-static.ts)
- [packages/core/package.json](https://github.com/blade47/fumadocs/blob/main/packages/core/package.json)
- [packages/core/src/search/client/orama-cloud.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/orama-cloud.ts)
- [packages/base-ui/src/components/dialog/search-orama.tsx](https://github.com/blade47/fumadocs/blob/main/packages/base-ui/src/components/dialog/search-orama.tsx)
- [packages/radix-ui/src/components/dialog/search-orama.tsx](https://github.com/blade47/fumadocs/blob/main/packages/radix-ui/src/components/dialog/search-orama.tsx)
- [packages/core/src/search/client/orama-cloud-legacy.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/orama-cloud-legacy.ts)
- [packages/openapi/src/ui/operation/index.tsx](https://github.com/blade47/fumadocs/blob/main/packages/openapi/src/ui/operation/index.tsx)
- [packages/openapi/src/server/index.tsx](https://github.com/blade47/fumadocs/blob/main/packages/openapi/src/server/index.tsx)
- [packages/create-app/template/+orama-cloud/@app/components/search.tsx](https://github.com/blade47/fumadocs/blob/main/packages/create-app/template/%2Borama-cloud/%40app/components/search.tsx)
- [packages/core/src/search/orama/create-db.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/create-db.ts)
- [packages/core/src/search/client/algolia.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/algolia.ts)
- [packages/core/src/search/orama/search/simple.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/search/simple.ts)
- [packages/core/src/search/orama-cloud.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama-cloud.ts)
- [packages/api-docs/src/components/schema/client.tsx](https://github.com/blade47/fumadocs/blob/main/packages/api-docs/src/components/schema/client.tsx)
- [packages/core/src/search/orama-cloud-legacy.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama-cloud-legacy.ts)
- [packages/core/src/search/orama/search/advanced.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/search/advanced.ts)
- [packages/core/src/search/flexsearch/utils.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/flexsearch/utils.ts)
- [packages/core/src/search/algolia.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/algolia.ts)
- [packages/core/src/search/server/build-index.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/server/build-index.ts)
- [packages/core/src/search/flexsearch.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/flexsearch.ts)
- [packages/create-app/template/+orama-cloud/@app/lib/export-static-indexes.ts](https://github.com/blade47/fumadocs/blob/main/packages/create-app/template/%2Borama-cloud/%40app/lib/export-static-indexes.ts)
- [packages/core/src/search/mixedbread.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/mixedbread.ts)
- [packages/core/src/search/server.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/server.ts)
- [packages/core/src/search/client/flexsearch-static.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/flexsearch-static.ts)
- [packages/preview/src/pages/_api/api/search.ts](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/pages/_api/api/search.ts)
- [packages/core/src/search/server/endpoint.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/server/endpoint.ts)
- [packages/core/src/search/client/mixedbread.ts](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/mixedbread.ts)
</details>

Orama Integration within the Fumadocs ecosystem provides a sophisticated, type-safe approach to full-text search. By leveraging Orama's high-performance search engine (both via Orama Cloud or static local databases), it enables developers to index documentation content dynamically. This integration solves the problem of keeping searchable content in sync with evolving documentation by providing utilities for both server-side indexing and client-side querying.

The system is designed around a modular architecture that separates document indexing logic from the querying interface. It treats documentation content as structured data, which is processed and serialized into searchable schemas (either simple or advanced/vector-capable). This abstraction ensures that search UI components—like the `OramaSearchDialog`—can remain decoupled from the underlying data source implementation while maintaining a unified developer experience.

By utilizing this integration, developers can leverage Orama's advanced capabilities, including vector search and faceted filtering, while maintaining compatibility with internationalization (i18n) and large-scale site structures. The integration ensures performance by providing mechanisms for debounced searching and cached database loading, minimizing browser overhead while maximizing retrieval accuracy.

## Search Server Initialization

The search server acts as the primary orchestrator for indexing documentation pages. It leverages `createSearchAPI` to define the search strategy, specifically supporting `'simple'` and `'advanced'` modes. The initialization process transforms raw source data (typically from the loader) into an Orama index.

The mechanism follows a pattern where content is processed into defined schemas. For `'advanced'` search, the schema includes `embeddings` (vector), `page_id`, and `tags`, enabling complex queries. The `createDB` and `createDBSimple` functions manage the ingestion of structured data into Orama's internal instances.

```mermaid
flowchart TD
    A["Loader / Source"] --> B["buildIndexDefault()"]
    B --> C["createSearchAPI()"]
    C --> D{"Type"}
    D -->|"simple"| E["initSimpleSearch()"]
    D -->|"advanced"| F["initAdvancedSearch()"]
    E --> G["createDBSimple()"]
    F --> H["createDB()"]
    G --> I["insertMultiple()"]
    H --> I
```
Sources: [packages/core/src/search/orama/create-server.ts:136-149](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/create-server.ts#L136-L149), [packages/core/src/search/orama/create-db.ts:32-82](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/create-db.ts#L32-L82)

## Orama Cloud Indexing Pipeline

When utilizing Orama Cloud, the system syncs local data to the cloud via a dedicated script. This pipeline is managed by a Fumadocs template plugin that generates a `sync-content.ts` script. This script fetches pre-rendered static indexes (serialized as `OramaDocument` objects) and pushes them to the Orama Cloud project via the Orama Cloud SDK.

The data transformation step, `toIndex`, is critical. It decomposes a single `OramaDocument` (representing a page) into multiple `OramaIndex` items: one for each section heading and one for the page description. This expansion allows the search engine to return precise document sections rather than just entire pages.

```mermaid
sequenceDiagram
    participant Build as Build System
    participant Script as sync-content.ts
    participant Cloud as Orama Cloud
    Build->>Script: Execute sync
    Script->>Script: Parse static.json
    Script->>Script: Perform toIndex() expansion
    Script->>Cloud: transaction.insertDocuments()
    Script->>Cloud: transaction.commit()
```
Sources: [packages/create-app/src/plugins/orama-cloud.ts:77-104](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/plugins/orama-cloud.ts#L77-L104), [packages/core/src/search/orama-cloud.ts:118-159](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama-cloud.ts#L118-L159)

> [!NOTE]
> When using `orama-cloud`, the search service is externalized. Ensure `NEXT_PUBLIC_ORAMA_PROJECT_ID` and `ORAMA_PRIVATE_API_KEY` are defined in the build environment to enable the synchronization task to authenticate successfully.

## Client-Side Search Interface

The `useDocsSearch` hook provides a unified API for interacting with various search backends, including `oramaStaticClient` and `oramaCloudClient`. It manages state (`search`, `isLoading`, `data`, `error`) and handles debouncing of input values to optimize search performance.

The hook operates using a `SearchClient` interface. When `oramaCloudClient` is invoked, it returns a search implementation that delegates query execution to the Orama Cloud SDK. If `index` is set to `'crawler'`, it performs a raw search against Orama Cloud's hits; otherwise, it handles group aggregation (`groupBy`) to ensure search results are presented hierarchically (pages with embedded sections).

Sources: [packages/core/src/search/client.ts:83-197](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client.ts#L83-L197), [packages/core/src/search/client/orama-cloud.ts:40-134](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/orama-cloud.ts#L40-L134)

## Advanced Search Logic and Sorting

Advanced search operations, specifically `searchAdvanced`, utilize Orama's `groupBy` feature to aggregate related search hits under a specific `page_id`. This prevents the search dialog from becoming cluttered with duplicate page entries if multiple sections of the same page match the query term.

The selection logic is implemented as follows:
1. Results are searched using Orama's full-text search.
2. If `groupBy` is defined, hits are clustered.
3. The results are iterated, and for every `group` found, the `page_id` is used to fetch the document representing the parent page.
4. The page title is pushed first, followed by sections.

This ensures a predictable and stable rendering order for the UI components.

Sources: [packages/core/src/search/orama/search/advanced.ts:6-77](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/search/advanced.ts#L6-L77)

## Configuration and Options

The Orama integration offers several configuration interfaces, primarily distinguished by the search mode (Simple vs. Advanced).

| Option | Type | Description |
| :--- | :--- | :--- |
| `indexes` | `Array` | The list of data documents to index. |
| `language` | `string` | The stemmer language to use for tokenization. |
| `tokenizer` | `object` | Custom tokenization strategy if the default is insufficient. |
| `tag` | `string` | Filter for search results in the UI. |
| `mode` | `'full'\|'vector'` | Enables vector search (requires `@orama/plugin-embeddings`). |

Sources: [packages/core/src/search/orama/create-server.ts:39-60](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/create-server.ts#L39-L60), [packages/core/src/search/orama/create-server.ts:151-163](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/create-server.ts#L151-L163)

> [!WARNING]
> Enabling `mode: 'vector'` requires installing `@orama/plugin-embeddings` separately. Failure to install this plugin will result in a runtime error during search execution because the internal vector search engine will be missing.

## Lifecycle and Caching

The integration employs aggressive caching to maintain performance. Specifically, `oramaStaticClient` uses a `cache` map indexed by the `from` (URL) property to ensure that the database is loaded only once per session. The `createFromSource` function in the server uses a `WeakMap` to associate `LoaderOutput` instances with their respective `SearchServer` instances.

This `WeakMap` implementation acts as a memory safety layer, allowing the garbage collector to reclaim server instances if the underlying `LoaderOutput` is discarded, effectively preventing memory leaks during hot-reloads or dynamic documentation updates.

Sources: [packages/core/src/search/client/orama-static.ts:34-93](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/client/orama-static.ts#L34-L93), [packages/core/src/search/orama/create-server.ts:278-314](https://github.com/blade47/fumadocs/blob/main/packages/core/src/search/orama/create-server.ts#L278-L314)

## Related

- [Search Indexing](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/search-subsystem/search-indexing)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/llms.txt) for all pages in this wiki.