Orientation
Content Processing
Search Infrastructure
Rendering and UI
Developer Tooling
How It Works
The following files were used as context for generating this wiki page:
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.
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.
Sources: packages/core/src/search/orama/create-server.ts:136-149, packages/core/src/search/orama/create-db.ts:32-82
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.
Sources: packages/create-app/src/plugins/orama-cloud.ts:77-104, packages/core/src/search/orama-cloud.ts:118-159
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.
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, packages/core/src/search/client/orama-cloud.ts:40-134
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:
groupBy is defined, hits are clustered.group found, the page_id is used to fetch the document representing the parent page.This ensures a predictable and stable rendering order for the UI components.
The Orama integration offers several configuration interfaces, primarily distinguished by the search mode (Simple vs. Advanced).
Sources: packages/core/src/search/orama/create-server.ts:39-60, packages/core/src/search/orama/create-server.ts:151-163
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.
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, packages/core/src/search/orama/create-server.ts:278-314