indexbind

indexbind builds retrieval artifacts offline, then opens them across Node, browsers, and Workers.

Docs: indexbind.jolestar.workers.dev

The release history is tracked in CHANGELOG.md.

What It Is

indexbind is an embedded retrieval library for fixed document sets.

Use it when:

• the document collection is known at build time
• retrieval should ship with your product or artifact
• the host application wants to control routing, filtering, and ranking policy
• the same retrieval data should work across Node, browsers, and Workers
• you do not want a hosted search dependency at query time

indexbind is not a hosted search service and not a turnkey knowledge-base product. It is a retrieval layer you embed into your own docs system, blog system, local tool, agent workflow, or publishing pipeline.

Public Contract

• build retrieval artifacts offline
• open a native SQLite artifact in Node
• open a canonical bundle in browsers, Workers, and Cloudflare Workers
• keep results document-first, with chunk evidence in bestMatch
• expose build and query APIs through a small library surface

Install

Install the Node package:

npm install indexbind

On supported platforms, npm also installs the matching native package automatically through optionalDependencies.

Current published prebuilt targets:

• macOS arm64
• macOS x64
• Linux x64 (glibc)

Windows native prebuilds are not included. On Windows, use WSL for install, build, and local Node query flows.

If a prebuilt addon is unavailable for your platform, install from source in a Rust toolchain environment and run:

npm run build:native:release

Start Quickly

1. Build a native SQLite artifact for Node:

npx indexbind build ./docs

This writes the artifact to ./docs/.indexbind/index.sqlite by default.

2. Query it from Node:

import { openIndex } from 'indexbind';

const index = await openIndex('./docs/.indexbind/index.sqlite');
const hits = await index.search('rust guide');

Or query it directly from the CLI:

npx indexbind search ./docs/.indexbind/index.sqlite "rust guide"
npx indexbind search ./docs/.indexbind/index.sqlite "rust guide" --text

3. Build a canonical bundle for browsers and Workers:

npx indexbind build-bundle ./docs

This writes the bundle to ./docs/.indexbind/index.bundle/ by default.

4. Or keep a mutable build cache and export fresh artifacts from it:

npx indexbind update-cache ./docs --git-diff
npx indexbind export-artifact ./index.sqlite --cache-file ./docs/.indexbind/build-cache.sqlite

CLI commands print JSON by default. Add --text when you want scan-friendly terminal output.

Index-Scoped Conventions

If a directory needs a small amount of host-specific shaping, place optional convention files next to its .indexbind/ output:

• indexbind.build.js
• indexbind.search.js

For example, if you index ./docs, these files live in ./docs/ and affect only the artifact rooted there.

indexbind.build.js can:

• skip selected documents
• derive canonicalUrl
• inject or normalize metadata
• adjust title or summary before indexing

indexbind.search.js can:

• define a default search profile for CLI and Node search
• rewrite the input query for lightweight alias expansion

This keeps small repo-specific search policy attached to the native indexbind pipeline instead of wrapper scripts.

Artifact Paths

• Native SQLite artifact: best fit for local Node retrieval
• Canonical bundle: best fit for browsers, Workers, and Cloudflare Workers
• Incremental build cache: best fit for repeated local rebuilds and host-controlled indexing workflows

Project Shape

The project scope is deliberately narrow:

• take a fixed document collection as input
• build a reusable retrieval artifact offline
• use local embedding models instead of hosted APIs
• expose a small library API that other systems can embed

Best Fit

indexbind works best when you want to:

• build search artifacts from a deterministic document set
• embed retrieval into another product, CLI, or publishing system
• index a local knowledge base while still owning the surrounding workflow
• ship search without depending on a hosted search service
• reuse the same retrieval model across Node, browsers, and Workers

Not the Best Fit

indexbind is usually not the right first choice when you want:

• a hosted search service with dashboards, analytics, and server-side index management
• a turnkey local knowledge-base product with its own end-user workflow
• a static-site search tool where the main requirement is dropping in a prebuilt UI and search script

Positioning

The easiest way to understand indexbind is by comparison:

• Pagefind is optimized for static-site search as a packaged product. indexbind is a lower-level retrieval library you embed into your own site, app, CLI, or worker.
• qmd overlaps with indexbind on local knowledge-base search. The main difference is product boundary: qmd is closer to a ready-made local search product, while indexbind is closer to a retrieval engine you embed into your own system. If your host wants to own routing, filtering, ranking policy, and artifact distribution, indexbind is usually the better fit.
• Meilisearch is a hosted or self-hosted search service. indexbind avoids the service boundary by building an artifact offline and opening it locally at runtime.

That makes indexbind a good fit for doc systems, local tools, local knowledge bases with host-defined workflow, publishing pipelines, and agent-facing products that want a reusable retrieval layer.

Documentation Paths

Use the docs by task:

• Getting Started
• Choosing indexbind
• Adoption Examples
• Benchmarks and Case Studies
• API Reference
• CLI Reference
• Web and Cloudflare
• Packaging
• Search Quality Controls

Documentation Site

• Documentation site
• Architecture
• Documentation site source

Name

Indexbind reflects the library's shape: build a fixed document set into a reusable retrieval artifact, then open that artifact locally to rank documents.