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.

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.

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