SurrealDB JavaScript SDK

Connect to remote and embedded SurrealDB instances

   

       

     

Documentation

View the SDK documentation here.

Learn SurrealDB

• A Tour of SurrealDB: https://surrealdb.com/learn/tour
• Aeon's Surreal Renaissance (Interactive book): https://surrealdb.com/learn/book
• Documentation: https://surrealdb.com/docs

Packages

This monorepo publishes several npm packages. Most applications only need surrealdb - install engine or utility packages when your use case requires them.

Package	npm	Description	Readme
surrealdb	surrealdb	Official database client - connect, query, live subscriptions, sessions	Read more
@surrealdb/sqon	@surrealdb/sqon	Value types, CBOR/JSON codecs, and core utilities (re-exported by surrealdb)	Read more
@surrealdb/wasm	@surrealdb/wasm	Embedded SurrealDB engine for browsers (mem://, indxdb://)	Read more
@surrealdb/node	@surrealdb/node	Embedded SurrealDB engine for Node.js, Bun, and Deno	Read more
@surrealdb/spectron	@surrealdb/spectron	Typed HTTP client for the Spectron AI memory API	Read more

Quick start

bun add surrealdb

import { Surreal } from "surrealdb";

const db = new Surreal();
await db.connect("wss://my-instance.aws-euw1.surreal.cloud");

For installation options, connection setup, query examples, live queries, embedded engines, and TypeScript notes, see the surrealdb package readme.

Contributing

Local setup

This is a Bun project, not Node.js. It works across all major runtimes, however.

Supported environments

• Deno
• Node.js
• Bun
• Web Browsers

Requirements

• Bun
• SurrealDB (for testing)

TypeScript

This SDK supports both TypeScript 5 and TypeScript 6. If you are using TypeScript 6, note that the default value for the types compiler option changed from auto-discovering all @types/* packages to []. You may need to explicitly add the types you depend on in your tsconfig.json:

{
    "compilerOptions": {
        "types": ["node"]
    }
}

Build for all supported environments

For Deno, no build is needed. For all other environments run:

bun run build

Code quality

bun run qa - apply formatting and safe fixes

bun run qau - apply formatting and unsafe fixes

bun run qc - check code quality

bun run qts - TypeScript type check

Run tests

bun run test - WebSocket protocol

SURREAL_DEFAULT_PROTOCOL=http bun test - HTTP protocol

PRs

Before you commit, please format and lint your code accordingly to check for errors, and ensure all tests still pass.

Editor extensions

For local development the Bun extension and Biome extension for VSCode are helpful.

Directory structure

• ./biome.json - code quality settings
• ./scripts - build and publish scripts
• ./packages/sdk - JavaScript SDK (surrealdb on npm)
• ./packages/sqon - SQON value types and codecs
• ./packages/node - embedded Node.js engine
• ./packages/wasm - embedded WebAssembly engine
• ./packages/spectron - Spectron HTTP client
• ./packages/tests - test suite (surrealdb/ for the SDK, spectron/ for Spectron)
• ./demo/wasm - WebAssembly demo
• ./demo/node - Node.js demo