Searchable

Searchable builds a static search index ahead of time and searches it in the browser. It provides search-service features without a query-time server, hosted API, or per-query bill. Try the live feature gallery to see real generated indexes searched by the browser client.

Why Searchable

• Deploy the index beside any static site or CMS export.
• Keep user queries in the browser.
• Fetch immutable, content-hashed shards only when a query needs them.
• Use an open JSON-first index format built by the Python searchable toolkit and read by the @ktjn/searchable TypeScript client, or by the searchable Python client for CLI and backend-service use — see the Python client API reference.
• Add richer search without adopting an application framework.

What it supports

• BM25F lexical ranking, field and document boosts, prefix queries, quoted phrases, and fuzzy matching
• Terms, range, and hierarchical facets with contextual counts
• Query-time synonyms and editorial term-to-page pins
• English, German, Swedish, Dutch, Bokmål, and Nynorsk analysis plus fallback segmenters for CJK and Southeast Asian scripts
• Cancellation, streaming partial results, highlighting, and lifecycle events
• JSON-only index shards (no binary codecs)

Public preview

The @ktjn/searchable npm package is published to GitHub Packages and the Python packages to PyPI from v* release tags. Configure the package registries before installing them, or evaluate the implemented search surfaces in the live feature gallery:

Before releasing, add the PyPI API token as the PYPI_API_TOKEN secret for the pypi GitHub environment.

See the Python client API reference for usage.

git clone https://github.com/ktjn/searchable.git
cd searchable
corepack enable
pnpm install
pnpm build
pnpm test

For npm, add @ktjn:registry=https://npm.pkg.github.com to .npmrc and provide a GitHub token with read:packages. Python packages are installed from the standard PyPI index:

uv add searchable

API shape

The package API builds and publishes an index, then creates a client that points at its manifest:

import { SearchClient } from "@ktjn/searchable";

const search = new SearchClient({
  indexUrl: "/search-index/manifest.json",
});

const result = await search.search("getting started");
for (const hit of result.hits) {
  console.log(hit.fields.title, hit.url);
}

See First search for a complete path and Indexing content for index production.

Documentation

• Overview
• Installation
• Guides
• Architecture
• Client API
• Configuration
• Roadmap

Development

Requires Node.js 24 or newer and pnpm 11.

pnpm install
pnpm build
pnpm test
pnpm typecheck
pnpm lint

The index generator (searchable.indexer, which discovers and analyzes source documents and writes the manifest and shards) and its shared analysis library (searchable.analysis) live in the consolidated Python project at python/searchable, which uses uv for development. Contributions should preserve deterministic output; see Project governance.

See Contributing before opening a pull request and report security issues through the private process in Security.

Status

The implemented package surface is released from v* tags to GitHub Packages. The lexical, facet, synonym, fuzzy, and pinning surfaces described in these docs are implemented. Planned work is collected only in the roadmap; historical investigations and superseded specifications live under docs/archive/.

License

MIT