Overview

Run ZBSearch as a distributed search API on Cloudflare Workers and R2 - full-text, vector, and hybrid search at the edge. Currently in beta.

Beta

Deploy to Cloudflare (ZBSearch Edge) is in beta. The Worker runtime, setup CLI, WAL/rebuild pipeline, and docs may change before a stable release. Expect rough edges - report issues on GitHub.

ZBSearch Edge is a self-hosted search API that runs on Cloudflare Workers with R2 as durable storage. It uses the same ZBSearch engine you already know from the browser and Node.js, but exposes it over HTTP with an append-only WAL and background rebuild pipeline optimized for edge deployments.

This is not a managed SaaS product. You deploy the Worker and R2 bucket to your own Cloudflare account. There is no control plane, billing integration, or vendor lock-in beyond standard Cloudflare infrastructure.

What you get

Capability	Details
Search modes	Full-text, vector, and hybrid search (same engine as `zbsearch`)
REST API	Create indexes, upsert/delete documents, search, rebuild, status
Edge latency	Queries served from Workers close to your users
Durable storage	Immutable snapshots and an append-only WAL in R2
Background rebuilds	In-Worker cron for small indexes, external builder for production, bulk `import` for large catalogs
OSS & free to deploy	Apache 2.0 - you only pay Cloudflare usage

Architecture

Writes and reads follow different paths by design. Writes are batched into WAL segments in R2, serialized per index by an IndexCoordinator Durable Object. Search loads the live snapshot from R2 and keeps it in a per-isolate deserialized cache (backed by the Workers Cache API across a colo), so warm queries skip R2 entirely. Pending WAL operations can be overlaid at query time until the next rebuild merges them. Indexes that outgrow a single snapshot can be created with N shards - writes route per document id and search scatters to all shards and merges the hits (API reference).

Client                    Cloudflare Worker                 R2
  │                              │                          │
  │  PUT /documents/:id          │  append WAL entry        │
  │ ───────────────────────────► │ ────────────────────────► │
  │  ◄── 202 buffered            │                          │
  │                              │                          │
  │  POST /rebuild (or cron)     │  read snapshot + WAL     │
  │ ───────────────────────────► │ ◄──────────────────────► │
  │                              │  write new snapshot      │
  │                              │ ────────────────────────► │
  │  POST /search                │  load snapshot (+ WAL)   │
  │ ───────────────────────────► │ ◄──────────────────────► │
  │  ◄── 200 hits                │                          │

Published npm packages

Package	Role
`@zbsearch/edge-core`	REST router, WAL, rebuild logic, search orchestration
`@zbsearch/runtime-cloudflare`	Workers entrypoint, setup/teardown CLIs
`@zbsearch/storage-s3`	S3-compatible driver for R2 (builder CLI)
`@zbsearch/edge-index-builder`	CLI to rebuild indexes and bulk-import snapshots

Setup and teardown CLIs ship with @zbsearch/runtime-cloudflare (zbsearch-edge-setup, zbsearch-edge-teardown). Config templates are included in the package under deploy/templates/.

When to use this

ZBSearch Edge fits when you want:

A globally distributed search API without running your own servers
Predictable read performance (snapshot loaded from R2, cached at the edge)
Infrequent or batched writes with acceptable eventual consistency (seconds to minutes, depending on rebuild schedule)
Bulk catalog loads via the import CLI (hundreds or thousands of documents in seconds)
Full-text, vector, or hybrid search with the same schema model as standalone ZBSearch

For purely local or single-process use cases, use the zbsearch library directly. Edge adds HTTP, persistence, and the WAL/rebuild pipeline on top.

Quick start

npm install @zbsearch/runtime-cloudflare wrangler
npx wrangler login
npx zbsearch-edge-setup --init

After deploy, Wrangler prints your Worker URL. See Setup for config files, R2 API tokens, optional auth, and rebuild configuration.

Next steps

Setup - prerequisites, R2, secrets, first deploy
API reference - every endpoint with examples
Indexing & rebuilds - how writes become searchable
Production - auth, GitHub Actions, webhooks
Benchmarks - load-testing harness and results
Local development - wrangler dev and testing