surrealdb/surrealdb.js

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.

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
• ./demo/expo - Expo / React Native demo