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).

Engine version

Each plugin runs a SurrealDB engine that ships as its own package: @surrealdb/wasm-native for WebAssembly and @surrealdb/node-native for Node.js. From plugin version 3.0.4, the engine is a peer dependency, so you choose which SurrealDB release runs embedded in your app, independently of the plugin version. Install a specific release with npm install --save @surrealdb/node-native@3.3.2, or let your package manager pick the newest release in the supported range. The Node.js and WebAssembly engine pages describe pinning and how to check the loaded version.

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 @surrealdb/wasm-native

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 @surrealdb/node-native

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