dazzle-react

React bindings for the Dazzle WebAssembly runtime. HNSW vector search + hash KV running 100% in the browser, persisted to OPFS, exposed as React hooks.

Same dazzle.wasm as the dazzle_flutter and dazzle-react-native packages — zero behaviour drift across all three web targets.

What's new in 1.0.0-beta.7.x

Eleven additive features landed across beta.7 → beta.7.2 — every one of them additive, no breaking ABI.

• DazzleServer.health() — typed DazzleHealth snapshot (uptime, memory, clients, keys, RDB / BGSAVE state, version).
• DazzleServer.healthFlow() / healthStream() — periodic emitter (Kotlin Flow / Swift AsyncStream).
• DazzleServer.bgSave() / bgRewriteAof() — typed wrappers with a sealed BgCheckpointResult (Started / AlreadyInProgress / NotRunning / Failed).
• DazzleServer.stopAsync() + commandWithTimeout() — suspend / async variants that respect coroutine cancellation and surface DazzleException.Timeout cleanly.
• VectorIndex.saveGraph() / loadGraph() — HNSW graph persistence MVP, fp32 cosine only this release.
• RecoveryMode.QUARANTINE_AND_COLD_START — opt-in: rename corrupt RDB / AOF artifacts to <name>.corrupt-<unix-ms> and boot cold instead of crash-looping.
• ExecutionPolicy.lowEnd / .midRange / .flagship — hand-tuned device-class presets.
• Granular stopReason on LlamaCppClient (Kotlin): distinguishes "eos" / "max_tokens" / "cancel" / "error" instead of conflating them.
• Delta.Usage / .usage(TokenUsage) — per-turn LLM telemetry (prompt / new tokens, prefill / decode latency).
• DazzleErrorCode frozen 1.0 ABI — 19 codes (0..18).
• IndexCapacityExceeded, PrefillAborted, IndexNotFound, Timeout typed exceptions across every SDK.

See CHANGELOG.md for the full prose and code snippets per platform.

Install

npm install dazzle-react

Setup

The package ships dazzle.wasm (~236 KB) + dazzle.js (~68 KB) under web/native/. Configure your bundler (Vite, Webpack, esbuild, …) to copy them as static assets, then load them as an ES module before your React app boots:

<!-- index.html -->
<script type="module">
  import dz from "/path/to/dazzle.js";
  globalThis.dazzleModule = dz;
</script>

Vite copy snippet

// vite.config.ts
import { viteStaticCopy } from 'vite-plugin-static-copy';

export default {
  plugins: [
    viteStaticCopy({
      targets: [{ src: 'node_modules/dazzle-react/web/native/*', dest: 'dazzle' }],
    }),
  ],
};

then point the loader script at /dazzle/dazzle.js.

Quick start

import {
  useDazzleInit,
  useDazzleHash,
  useVectorIndex,
  useVectorSearch,
} from 'dazzle-react';

export function App() {
  const { ready, error } = useDazzleInit();
  if (error)  return <p>Failed to load Dazzle: {error.message}</p>;
  if (!ready) return <p>Loading…</p>;

  return <Catalog />;
}

function Catalog() {
  const hash  = useDazzleHash('chat:1');
  const index = useVectorIndex('catalog');

  const handleSeed = () => {
    index.create({ dim: 1536 });
    index.add('product-1', new Float32Array(/* 1536 floats */));
    hash.set('lastSeededAt', Date.now().toString());
  };

  const { hits } = useVectorSearch('catalog', queryEmbedding, { topK: 5 });
  return (
    <ul>
      {hits.map(h => <li key={h.id}>{h.id} (d={h.distance.toFixed(3)})</li>)}
    </ul>
  );
}

Imperative API

If you don't want hooks, the underlying class API works just fine:

import { DazzleWeb } from 'dazzle-react';

await DazzleWeb.initialize();
DazzleWeb.hash('chat:1').set('role', 'user');
const hits = DazzleWeb.vectorIndex('catalog').search(query, { topK: 5 });
await DazzleWeb.persist();

Hooks

| Hook | Returns | Use | |---|---|---| | useDazzleInit({ opfsFileName? }) | { ready, error } | Boot the runtime once near the root | | useDazzleHash(key) | DazzleWebHash | Stable handle to a hash | | useVectorIndex(name) | DazzleWebVectorIndex | Stable handle to a vector index | | useVectorSearch(name, query, opts?) | { hits, refresh } | Re-runs search when query changes | | useAutoPersist() | void | Snapshot to OPFS on unmount |

Scope (1.0.0-beta.6)

• ✅ Hash KV (HSET/HGET/HGETALL/HDEL)
• ✅ Vector index (HNSW): create / add / addBatch / search / drop
• ✅ Snapshot persistence to OPFS

Out of MVP for web (use the iOS/Android/Desktop targets):

• Lists / Sets / SortedSets / Streams standalone primitives
• On-device LLM clients (LlamaCpp, LiteRT-LM, FoundationModels)

React Native?

If you're on React Native (with or without web target), use dazzle-react-native instead — it ships native bindings for iOS / Android plus the same WASM bridge for RN Web.

Changelog

See CHANGELOG.md for per-version notes, or the repo CHANGELOG for cross-stack release notes.

License

Apache 2.0.