README.md

@surrealdb/wasm

Embedded SurrealDB engine for the browser

   

   

Documentation

View the JavaScript SDK documentation here, including the embedded engines concept page and the WebAssembly engine reference.

What is this package?

@surrealdb/wasm is a WebAssembly engine plugin for the SurrealDB JavaScript SDK. It runs SurrealDB inside the browser - in-memory or persisted to IndexedDB - with the same query API as a remote instance.

Install it alongside surrealdb and register the engine when constructing your client. For server-side embedding, use @surrealdb/node instead.

How to install

This package has a peer dependency on surrealdb. Install both:

# using npm
npm i surrealdb @surrealdb/wasm

# or using pnpm
pnpm i surrealdb @surrealdb/wasm

# or using yarn
yarn add surrealdb @surrealdb/wasm

# or using bun
bun add surrealdb @surrealdb/wasm

Getting started

Register the WebAssembly engine when you create a Surreal client, then connect to an embedded endpoint:

import { createWasmEngines } from "@surrealdb/wasm";
import { Surreal } from "surrealdb";

const db = new Surreal({
    engines: createWasmEngines(),
});

await db.connect("mem://");

await db.use({ namespace: "test", database: "test" });

await db.query("CREATE person SET name = 'Tobie'");

To connect to remote SurrealDB instances as well as embedded databases, combine the WebAssembly engine with the SDK's remote engines:

import { createWasmEngines } from "@surrealdb/wasm";
import { Surreal, createRemoteEngines } from "surrealdb";

const db = new Surreal({
    engines: {
        ...createRemoteEngines(),
        ...createWasmEngines(),
    },
});

Storage backends

// In-memory (data is lost when the tab closes)
await db.connect("mem://");

// IndexedDB persistence
await db.connect("indxdb://myapp");

Running in a Web Worker

Offload database work from the main thread to keep your UI responsive:

import { createWasmWorkerEngines } from "@surrealdb/wasm";
import WorkerAgent from "@surrealdb/wasm/worker?worker";
import { Surreal, createRemoteEngines } from "surrealdb";

const db = new Surreal({
    engines: {
        ...createRemoteEngines(),
        ...createWasmWorkerEngines({
            createWorker: () => new WorkerAgent(),
        }),
    },
});

await db.connect("mem://");

The @surrealdb/wasm/worker export provides a pre-built worker script for bundlers that support the ?worker import suffix (such as Vite).

Connection options

Pass optional engine configuration to createWasmEngines or createWasmWorkerEngines:

const db = new Surreal({
    engines: createWasmEngines({
        strict: true,
        query_timeout: 30_000,
    }),
});

Usage with Vite

When using Vite, exclude the WASM package from dependency optimisation and enable top-level await:

// vite.config.js
export default {
    optimizeDeps: {
        exclude: ["@surrealdb/wasm"],
        esbuildOptions: {
            target: "esnext",
        },
    },
    esbuild: {
        supported: {
            "top-level-await": true,
        },
    },
};

Package contents

Export	Description
createWasmEngines(options?)	Registers mem and indxdb engines on the main thread
createWasmWorkerEngines(options?)	Registers mem and indxdb engines inside a Web Worker
@surrealdb/wasm/worker	Worker entry point for bundler worker imports
WebAssemblyEngine	The underlying engine implementation (advanced use)

Requirements

• ES modules (import) - CommonJS (require) is not supported
• A compatible surrealdb SDK version (see peerDependencies in package.json)
• A modern browser with WebAssembly and IndexedDB support

Contributing

This package is part of the surrealdb.js monorepo. See the main README for local setup, build commands, and contribution guidelines.