Local development

Run and test ZBSearch Edge locally with Wrangler dev, the rebuild CLI, and the monorepo test suite. Cloudflare deploy is in beta.

You can develop against ZBSearch Edge without deploying to Cloudflare on every change. Local development uses Wrangler's dev server with emulated R2 bindings and optional remote R2 for integration testing.

Start the local Worker

From the monorepo root:

wrangler dev --config deploy/cloudflare/wrangler.toml

Wrangler serves the Worker at http://127.0.0.1:8787 by default. Local R2 data persists under .wrangler/state/ in the project.

First-time setup

Install dependencies and build edge packages:

pnpm install
pnpm --filter @zbsearch/edge-core build

You do not need a remote R2 bucket for basic local dev - Wrangler simulates R2 locally.

Exercise the API locally

export WORKER_URL=http://127.0.0.1:8787

curl -X POST "$WORKER_URL/v1/indexes" \
  -H 'content-type: application/json' \
  -d '{"name":"local","schema":{"title":"string"}}'

curl -X PUT "$WORKER_URL/v1/indexes/local/documents/1" \
  -H 'content-type: application/json' \
  -d '{"title":"Local Dev Test"}'

curl -X POST "$WORKER_URL/v1/indexes/local/rebuild"

curl -X POST "$WORKER_URL/v1/indexes/local/search" \
  -H 'content-type: application/json' \
  -d '{"term":"local"}'

Local rebuild and import CLI against remote R2

To test the builder CLI against a real R2 bucket while developing:

Create a dev bucket: wrangler r2 bucket create zbsearch-edge-dev
Fill in deploy/cloudflare/.env with R2 API credentials
Build and run:

source deploy/cloudflare/.env  # or export vars manually
pnpm --filter @zbsearch/edge-index-builder build
node packages/edge-index-builder/dist/cli.js rebuild --all

Bulk-import a JSON catalog (builds snapshot locally, uploads to R2):

node packages/edge-index-builder/dist/cli.js import local-dev ./catalog.json \
  --create --name local-dev --schema-file ./schema.json

The CLI uses @zbsearch/storage-s3 to read/write the same R2 paths as the Worker.

Project layout

deploy/cloudflare/
  wrangler.toml         ← Worker config, R2 + Durable Object bindings, cron, vars, cpu_ms
  .env.example          ← R2 credentials template for CLI/CI
  ingest-unicorns.sh    ← Example bulk import script
  README.md             ← Quick reference

packages/
  edge-core/            ← REST API, WAL, rebuild, search logic
  runtime-cloudflare/   ← Worker entrypoint + deploy templates
  storage-s3/           ← S3-compatible storage driver
  edge-index-builder/   ← Rebuild + bulk import CLI

Running tests

The edge stack has automated tests that run in CI without Cloudflare credentials:

# All edge tests
pnpm --filter @zbsearch/edge-core test          # router, WAL, rebuild, import
pnpm --filter @zbsearch/storage-s3 test         # S3 driver + mock integration
pnpm --filter @zbsearch/edge-index-builder test # import + rebuild CLI
pnpm --filter @zbsearch/runtime-cloudflare test # Worker HTTP + cron + R2 adapter

# Full monorepo
pnpm test

Test layers

Layer	Package	What it validates
Unit	`edge-core`	Codec, paths, WAL ops, registry
Service	`edge-core`	Create, WAL, rebuild, import, search, cache
HTTP	`edge-core`	Every REST route and auth
Worker e2e	`runtime-cloudflare`	`worker.fetch()` with mock R2 and Cache
S3 integration	`storage-s3`	Mock S3 client + full rebuild flow

Worker tests mock R2 and caches.default in Node - no wrangler dev process required in CI.

Dry-run deploy

Verify the Worker bundle builds without deploying:

pnpm --filter @zbsearch/runtime-cloudflare build

This runs wrangler deploy --dry-run using packages/runtime-cloudflare/deploy/wrangler.monorepo.toml and outputs the bundle to packages/runtime-cloudflare/dist.

Docs site

Preview this documentation locally:

pnpm docs:dev

Open the docs app and navigate to Deploy to Cloudflare in the sidebar.

Tips

Hot reload

Wrangler dev reloads the Worker when source files change. Changes to @zbsearch/edge-core require rebuilding that package:

pnpm --filter @zbsearch/edge-core build

Consider running a watch command in a second terminal during active core development.

Testing with API keys locally

Set secrets for local dev:

wrangler secret put WRITE_API_KEY --config deploy/cloudflare/wrangler.toml
wrangler secret put READ_API_KEY --config deploy/cloudflare/wrangler.toml

Or temporarily remove auth by not setting the secrets - local dev defaults to open access.

Remote dev with real R2

To bind local Wrangler to remote R2 (shared state with a deployed environment), use Wrangler's remote mode flags per the Cloudflare dev docs. Useful for debugging production data issues - use a non-production bucket.

Clearing local state

Delete .wrangler/state/ to reset local R2 emulation:

rm -rf .wrangler/state

Next steps

Setup - deploy to Cloudflare
API reference - endpoint details
Production - CI and hardening

Local development

On this page