Querylight TS Demo

Introducing Querylight TS

Why this TypeScript port exists, who it is for, and where it fits relative to established search tools.

Back to docs search

Reference Entry

Introducing Querylight TS

Overview · foundation · order 10

Why this TypeScript port exists, who it is for, and where it fits relative to established search tools.

Relevant APIs

DocumentIndex TextFieldIndex VectorFieldIndex GeoFieldIndex

Tags

overview browser static-sites search vector geo

Introducing Querylight TS

Querylight TS is a TypeScript port of the original querylight library, built for browser and Node.js use cases where shipping a full search server would be excessive.

The project focuses on a practical middle ground: more capable than simple fuzzy matching libraries such as fuse.js, much smaller in scope than a full Lucene-based search stack. Within that local-first segment, it is positioned as the most feature-rich option for static sites, browser apps, demos, documentation portals, and other small to medium datasets. For the reasoning behind that positioning, see Comparing Querylight TS to Other Browser Search Libraries.

The practical benefit is that one library can cover classic lexical retrieval, dense vector retrieval, sparse vector retrieval, and hybrid ranking. You can start with a search box and later add chunk retrieval, related articles, sparse neural retrieval, hybrid lexical-plus-vector ranking, faceted navigation, or geo-aware filtering without replacing your document model or shipping a second local search stack.

Who it is for

Querylight TS is a good fit if you have a static website or browser application and want search features without depending on a remote backend for every query.

Typical use cases include:

  • Full-text search for documentation, blogs, and content-heavy static sites
  • Search-as-you-type suggestions
  • Faceting and filtering over structured metadata
  • Geo search for location-aware content
  • Dense vector search for similarity and recommendation features
  • Sparse neural search over token-weight vectors
  • Semantic search over chunked content
  • Related-article and “read next” suggestions
  • Offline or local-first retrieval experiments in the browser

If you want to get ambitious, you can even pair it with in-browser or WASM-based embedding models and keep the entire retrieval pipeline client-side.

Where it came from

The original Querylight project started as a hobby project built around tries and lightweight term matching. Over time it grew into a broader retrieval toolkit with TF-IDF ranking, BM25, phrase queries, aggregations, geo search, vector search, and query composition.

That evolution reflects my own background. I have spent most of my career working with search systems such as Lucene, Solr, Elasticsearch, and OpenSearch. Querylight TS is informed by that experience, but it is intentionally not trying to reproduce those systems in miniature.

The TypeScript port exists because modern browser applications increasingly need search features that are local, portable, and easy to ship. With current AI-assisted coding workflows, building and iterating on the port became much faster. That changes how the code gets written, but it does not remove the need for sound information retrieval concepts, testing, and engineering discipline.

What you can build with it

Querylight TS supports several retrieval patterns under one API:

  • Lexical search with TF-IDF and BM25 ranking
  • Structured boolean queries
  • Phrase queries and prefix expansion
  • Aggregations and significant terms
  • Dense vector similarity search
  • Sparse vector retrieval with token-weight maps
  • Geo indexing and querying
  • JSON-serializable index state for build-time generation and browser hydration

That combination lets the same local index support more than a search box. It can also power related articles, typo-tolerant discovery, filtered navigation, and hybrid lexical plus vector ranking.

Is it better than X?

Usually that is the wrong question.

If you want the detailed version of that answer, read Comparing Querylight TS to Other Browser Search Libraries.

There are many search libraries and products, and search is one of those domains where people regularly build a side project and then claim it replaces Elasticsearch. Querylight TS targets a different problem size from Elasticsearch, OpenSearch, Solr, and Lucene. Those systems are far more mature, scalable, and operationally complete.

The better question is whether Querylight TS is the right amount of search for your problem.

If you need distributed indexing, large-scale operations, advanced relevance tooling, or the broad ecosystem around established search servers, use those tools.

If you need a lightweight in-process search toolkit for browser or Node.js applications, Querylight TS may be a better fit.

Compared to smaller client-side libraries such as fuse.js, Querylight TS aims to cover a wider slice of retrieval functionality. fuse.js is excellent at being simple, useful, and easy to adopt, and it is often the right choice when all you need is straightforward fuzzy matching. Querylight TS gives you more building blocks when your application needs structured queries, facets, vectors, or geo features.

Repositories