WebAssembly engine

The @surrealdb/wasm package is a plugin for the JavaScript SDK that allows you to run SurrealDB as an embedded database within a browser environment. It supports in-memory databases and persistent storage via IndexedDB, and can optionally run inside a Web Worker to keep the main thread responsive.

Important

This package works with ES modules (import), not CommonJS (require).

Installing the WASM engine

Before installing the WASM engine, you need the core JavaScript SDK installed. Then add the @surrealdb/wasm package.

npm install --save @surrealdb/wasm

yarn add @surrealdb/wasm

pnpm install @surrealdb/wasm

Registering the engine

Import createWasmEngines from @surrealdb/wasm and spread it into the engines option alongside createRemoteEngines from the core SDK. This registers the embedded protocols while keeping remote connections available.

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

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

Supported connection protocols

Once the WASM engine is registered, you can connect to SurrealDB using the embedded protocols.

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

await db.connect('indxdb://myapp');

Remote protocols (ws://, wss://, http://, https://) remain available when createRemoteEngines() is also registered.

Running in a Web Worker

The WASM engine can run inside a Web Worker to offload database operations from the main thread. This keeps your interface responsive during computationally intensive queries.

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

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

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

Configuring your bundler

If you are using a bundler like Vite, you may need to exclude the WASM package from dependency optimization and enable top-level await.

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

Learn more

• WebAssembly engine reference for additional engine configuration
• Connecting to SurrealDB for connection options and reconnection behavior
• @surrealdb/wasm on npm