jazz-wasm

2.0.0-alpha.2 verified Sat Apr 25 auth: no javascript

WebAssembly bindings for the Jazz database engine, a local-first, real-time collaborative CRDT database. This package provides a WASM build of the core cojson library, enabling high-performance use in browser and Node.js environments. Current stable version is v0.20.17, with alpha releases for v2.0.0. Jazz is built on top of the CoJSON CRDT library and supports transparent sync, offline-first, and conflict-free replicated data types (CRDTs). Key differentiators include automatic conflict resolution, no central server required, and integrated reactive queries for real-time UI updates. Jazz-wasm specifically targets environments where native bindings are unavailable or where a portable binary is needed. It ships TypeScript types and is designed to be used alongside jazz-tools.

Common errors

error Error: Cannot find module 'jazz-wasm' ↓

cause Package not installed or incorrect import path.

fix

Run 'npm install jazz-wasm@latest' and ensure import path is correct (e.g., 'import 'jazz-wasm'').

error TypeError: Failed to fetch dynamically imported module: https://example.com/jazz-wasm.wasm ↓

cause WASM file cannot be loaded (CORS, missing file, or non-secure context).

fix

Verify the WASM file is served at the correct location, enable CORS if needed, and use HTTPS/localhost.

error Uncaught (in promise) RuntimeError: memory access out of bounds ↓

cause Corrupt WASM binary or mismatch between jazz-wasm version and cojson version.

fix

Ensure jazz-wasm and cojson versions match (e.g., both 0.20.x). Clear cache and reinstall.

Warnings

breaking jazz-wasm v2.0.0-alpha drops support for CommonJS require(). Use ESM imports only. ↓

fix Change require() calls to import statements. If necessary, use dynamic import() as a fallback.

deprecated The 'jazz-wasm' package is being renamed to 'cojson-core-wasm' starting from v0.20.17. ↓

fix Update imports to use 'cojson-core-wasm' instead of 'jazz-wasm'.

gotcha jazz-wasm must be imported before any jazz-tools or cojson usage. Failure results in missing WASM module errors. ↓

fix Ensure 'jazz-wasm' (or 'cojson-core-wasm') is imported at the very top of your entry point.

gotcha The WASM module requires a secure context (HTTPS or localhost) in browsers. Mixed content may block loading. ↓

fix Serve your application over HTTPS in production. During development, use localhost.

Install

npm install jazz-wasm

yarn add jazz-wasm

pnpm add jazz-wasm

Imports

default
```
import 'jazz-wasm'
```
jazz-wasm is a side-effect import that initializes the WASM module. You must import it before using jazz-tools or cojson.
initialize
wrong
```
const { initialize } = require('jazz-wasm')
```
correct
```
import { initialize } from 'jazz-wasm'
```
The package is ESM-only, especially since v2.0.0-alpha. CommonJS require may fail in Node.js.
ready
wrong
```
import { waitForReady } from 'jazz-wasm'
```
correct
```
import { ready } from 'jazz-wasm'
```
The export is named 'ready', not 'waitForReady'. It is a Promise that resolves when the WASM module is fully loaded.

Quickstart

Shows basic usage: import jazz-wasm for WASM initialization, then use jazz-tools co API to create and observe a collaborative counter.

import 'jazz-wasm';
import { co } from 'jazz-tools';

// Create a simple collaborative counter
const counter = co.create({ value: 0 });

// Listen for changes
counter.subscribe(() => {
  console.log('Counter:', counter.value);
});

// Update the counter
counter.value += 1;