Orama

Orama is a high-performance, dependency-free search engine built entirely in TypeScript that runs wherever JavaScript runs—browsers, Node.js, Deno, and edge runtimes like Cloudflare Workers—without requiring any external infrastructure. It ships as a single, tree-shakeable ES module under 2KB and supports full-text search with BM25 ranking, vector search with configurable embedding dimensions, and hybrid search that merges both approaches with configurable weighting.

Beyond raw search, Orama provides a complete RAG (Retrieval-Augmented Generation) pipeline through its AnswerSession API, which retrieves relevant documents from the search index and feeds them into OpenAI-compatible chat models to deliver ChatGPT-style conversational responses. The plugin ecosystem extends this with automatic embedding generation at insert time via TensorFlow.js, a secure proxy plugin for calling OpenAI APIs from the browser without exposing API keys, and framework integrations for Vitepress, Docusaurus, Astro, and Nextra.

Orama’s text analysis layer includes BM25 scoring, stemming in over 30 languages (including Chinese and Japanese), diacritics normalization, configurable stop words, typo tolerance via Levenshtein distance on a radix tree index, exact match mode, and field boosting. Structured search is handled through filters on string, number, boolean, and enum fields, faceted navigation, geospatial search via geopoint coordinates, result grouping, and merchandising rules (pinning) that let you force specific documents to the top of results.

The project is organized as a pnpm monorepo with Turbo orchestrating the build graph across 18 packages. The core engine is tested by 46 test files using the tap framework with c8 coverage, Playwright browser smoke tests, and tsd for TypeScript type-level tests. Installation is a single npm command or a direct CDN import for browser use cases, with full documentation at docs.orama.com.

What You Get

• Full-Text Search with BM25 - Delivers relevance-ranked search results using the BM25 algorithm, with support for field boosting, exact match, typo tolerance via Levenshtein distance, and stemming across 30+ languages including Chinese and Japanese.
• Vector and Hybrid Search - Performs cosine similarity search against vector embeddings stored alongside documents, with a hybrid mode that merges BM25 and vector scores using configurable weights for balanced keyword and semantic relevance.
• RAG-Powered AnswerSession - Provides a ChatGPT/Perplexity-style conversational search experience by retrieving documents from the index and feeding them as context into OpenAI-compatible chat models, with real-time streaming state updates for reactive UI rendering.
• Geosearch - Indexes and queries geographic coordinates using a dedicated geopoint data type, supporting radius-based filtering and distance-aware ranking for location-aware applications.
• Search Filters and Facets - Applies structured filters on string, number, boolean, and enum fields; generates dynamic facet counts for UI drill-downs; and supports result grouping for category-based navigation.
• Merchandising (Pinning Rules) - Forces specific documents to appear at fixed positions in search results using configurable pinning rules, enabling editorial or promotional control over result ordering.
• Plugin System - Extends the core engine with officially maintained plugins for auto-generating text embeddings via TensorFlow.js, calling OpenAI securely from the browser, persisting indexes, collecting analytics, and integrating with Vitepress, Docusaurus, Astro, and Nextra.
• Multi-Platform Support - Runs identically on Node.js, Deno, browsers via CDN, and edge runtimes using a single ES module with no native dependencies or backend services required.

Common Use Cases

• Client-side product catalog search - An e-commerce team embeds Orama directly in the frontend, indexing product names, descriptions, and categories at build time to deliver instant, typo-tolerant filtered search without any backend API calls.
• Documentation site with AI chat - A developer tools company adds Orama to their Docusaurus or Vitepress site using the official plugins, then wires up plugin-embeddings and plugin-secure-proxy to let users ask natural-language questions about the documentation answered by GPT-4o-mini.
• Edge-deployed semantic search - A media platform deploys Orama inside a Cloudflare Worker with pre-built vector embeddings, serving low-latency hybrid search across thousands of articles to users worldwide without origin server round-trips.
• Multilingual content search - A global SaaS product uses Orama’s 30+ language stemming and tokenization to enable accurate full-text search across Japanese, French, and German content in a single index without any language detection middleware.
• In-app instant search with facets - A developer tools dashboard indexes log entries and configuration objects in Orama and surfaces them through a faceted UI with live filtering by severity, timestamp range, and boolean flags, all running in the browser.
• Merchandised search for digital storefronts - An online marketplace uses Orama’s pinning rules to promote featured listings or sponsored items to the top of search results while preserving relevance ranking for the remaining results.

Under The Hood

Architecture Orama is organized as a pnpm monorepo with Turbo orchestrating a dependency-aware build graph across a core search engine and a suite of independently versioned plugin packages. The core engine follows a layered, component-injectable architecture: a thin method layer (create, insert, search, remove, update) delegates to swappable component implementations for document storage, indexing, tokenization, sorting, and pinning. The three search modes—fulltext via a radix tree and BM25, vector via a flat cosine similarity index, and hybrid via score merging—are cleanly separated code paths that converge at the result set level. A lifecycle hook system allows plugins to intercept before and after create, insert, and search operations without coupling to internals. The turbo build graph enforces correct build ordering across stemmers, tokenizers, and plugins.

Tech Stack The engine is written in TypeScript and built with tshy, which emits separate ESM, CommonJS, browser, and Deno dialect bundles from a single source tree. SWC provides fast incremental compilation during development, and Biome handles code formatting across the monorepo. The text processing pipeline uses a hand-rolled radix tree for typo-tolerant full-text indexing, a BKD tree for geospatial range queries, a flat array for vector cosine similarity, and an AVL tree for sort operations—all implemented in pure TypeScript with zero native dependencies. Plugins extend the engine with TensorFlow.js for local embedding generation, OpenAI for cloud LLM calls, and framework adapters for Astro, Vitepress, Docusaurus, and Nextra. Testing runs on the tap framework with Playwright for browser-environment smoke tests.

Code Quality The project ships 46 test files covering every public API surface—full-text search, vector search, hybrid search, filters, facets, geosearch, boosting, distinct, grouping, serialization, and TypeScript type correctness via tsd—alongside extensive edge case coverage for nested properties, large datasets, and error paths. Error handling uses a centralized error registry that generates descriptive, sprintf-formatted messages keyed by error code, surfacing actionable diagnostics for every invalid schema, vector size mismatch, or unsupported component. TypeScript generics flow through the entire API, making schema types propagate to insert, search, and result types at compile time. Biome enforces consistent formatting, and husky with lint-staged gates every commit behind format checks.

What Makes It Unique Orama is one of very few libraries that combines a complete, production-ready search engine—radix tree full-text, BKD geospatial, flat vector cosine similarity, BM25 ranking—with an integrated RAG pipeline, all in a single dependency-free TypeScript package that fits under 2KB and runs natively in the browser. The hybrid search implementation merges min-max normalized BM25 scores with cosine similarity scores using user-configurable weights, giving developers explicit control over the semantic-vs-keyword balance in a single query. The AnswerSession abstraction layers a streaming ChatGPT-style conversation API directly on top of the search index, so retrieved documents serve as grounding context without any external retrieval service. This end-to-end path from document insertion through vector embedding, hybrid retrieval, and LLM-grounded chat response—entirely in JavaScript—is a genuinely unusual capability for a library of this footprint.

Self-Hosting

Orama is licensed under the Apache License 2.0, a permissive open source license that allows free use, modification, and distribution for any purpose including commercial applications. There are no copyleft obligations that would require you to release your own source code; you can embed Orama in proprietary software and distribute it without disclosing your application’s code. The only requirements are preserving the copyright notice and the license text in your distribution.

Running Orama in production is operationally straightforward because the library is purely client-side or embedded—there is no server process to deploy, no database to manage, and no infrastructure to provision. You are responsible for building and serializing your search index at deploy time (or at runtime in the browser), deciding how to distribute it to your users, and keeping the library version current as upstream releases improvements. For large indexes, memory and bundle size become considerations that you manage at the application level. The plugin-data-persistence package provides utilities for saving and restoring serialized indexes, but backup and storage are your responsibility.

OramaSearch Inc. offers a managed cloud platform, Orama Cloud, which handles index hosting, synchronization, CDN distribution, analytics, and automatic updates. Compared to the self-hosted library, the cloud tier adds managed uptime and SLAs, built-in analytics dashboards, seamless integration with popular data sources, and commercial support—capabilities you would otherwise need to build and maintain yourself. The open source library gives you full control and zero ongoing cost, while the cloud offering trades that control for operational convenience and enterprise support channels.