WebAssembly (Wasm)

This library is a plugin for the SurrealDB JavaScript SDK, which can be used to run SurrealDB as an embedded database within a frontend or client-side web browser environment.

It enables SurrealDB to be run in-memory, or to persist data by running on top of IndexedDB. It allows for a consistent JavaScript and TypeScript API when using the surrealdb.js library by adding support for embedded storage engines (memory, indxdb) alongside the remote connection protocols (http, https, ws, wss).

The WebAssembly engine is available on NPM as @surrealdb/wasm and is required to be used as a plugin within the JavaScript SDK.

Important

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

Installation

Before installing the WebAssembly engine, you need to install the JavaScript SDK using the instructions in the installation documentation.

After installing the SDK, install the Wasm engine using the following command:

npm install --save @surrealdb/wasm

yarn add @surrealdb/wasm

pnpm install @surrealdb/wasm

Configuration

To use the Wasm engine, you need to import the surrealdbWasmEngines function from the @surrealdb/wasm package, and pass it as an option to the Surreal constructor.

import { Surreal } from 'surrealdb';
import { surrealdbWasmEngines } from '@surrealdb/wasm';

After importing the surrealdbWasmEngines function, you can pass it as an option to the Surreal constructor.

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

If you are using a bundler like Vite, Webpack, or Parcel, you can import the surrealdbWasmEngines function directly. For example, using Vite, place the following in your vite.config.js file:

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

Connecting

Using the .connect() method, you can connect to a SurrealDB instance. The connection string specifies whether to connect to the Wasm engine, in memory or persisted with the mem:// or indxdb:// prefixes respectively.

Example

index.js
import { Surreal } from 'surrealdb';
import { surrealdbWasmEngines } from '@surrealdb/wasm';

// Enable the WebAssembly engines
const db = new Surreal({
    engines: surrealdbWasmEngines(),
});

// Now we can start SurrealDB as an in-memory database

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

// Or we can start a persisted IndexedDB database

await db.connect("indxdb://demo");

// Now use the JavaScript SDK as normal.

Next steps

After setting up the Wasm engine, you can continue with the rest of the SDK documentation. You can refer to the methods documentation for more information on using SurrealDB with the Wasm engine also see the data types documentation for more information on how to use the data types supported by SurrealDB.

Sources

• @surrealdb/wasm on NPM
• GitHub repository