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.
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
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.
| Protocol | Description |
|---|
mem:// | In-memory database (data is lost when the page reloads) |
indxdb:// | Persistent database backed by IndexedDB |
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
