Embedded engines

The JavaScript SDK supports running SurrealDB as an embedded database through two engine plugins. Choose the one that matches your environment:

Both plugins work with ES modules (import), not CommonJS (require).

WebAssembly engine (browser)

The @surrealdb/wasm package runs SurrealDB inside 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.

Installation

npm install --save @surrealdb/wasm

Registering the engine

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

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

await db.connect('mem://');
// or persist with IndexedDB:
await db.connect('indxdb://myapp');

Running in a web worker

Offload database operations from the main thread to keep your interface responsive:

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://');

Bundler configuration

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

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

Node.js engine (server)

The @surrealdb/node package runs SurrealDB within Node.js, Bun, or Deno. It supports in-memory databases and persistent storage via RocksDB and SurrealKV.

Installation

npm install --save @surrealdb/node

Registering the engine

import { Surreal, createRemoteEngines } from 'surrealdb';
import { createNodeEngines } from '@surrealdb/node';

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

await db.connect('mem://');
// or persist with SurrealKV:
await db.connect('surrealkv://./data');

To enable versioned storage for temporal queries, append ?versioned=true to the connection string:

await db.connect('surrealkv://./data?versioned=true');

Closing the connection

When using the Node.js engine, you must close the connection with .close() when you are done to ensure the database is properly shut down:

await db.close();

Learn more

• •

  WebAssembly engine reference

• •

  Node.js engine reference

• •

  Connecting to SurrealDB for connection options and reconnection behaviour

• •

  @surrealdb/wasm on npm

• •

  @surrealdb/node on npm