Sandro Circi
MeProjects

//nuxt-surrealdbbysandros94

nuxt-surrealdb

A Nuxt module aimed to simplify the use of SurrealDB.

45
1
45
5
TypeScript
View on GitHubWebsite

nuxt-surrealdb

Nuxt SurrealDB

npm version
npm downloads
License
Nuxt

A Nuxt module aimed to simplify the use of SurrealDB, wrapping the official surrealdb.js SDK.

Quick Setup

Install the module to your Nuxt application:

npx nuxi module add nuxt-surrealdb

Configure your SurrealDB endpoint in nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-surrealdb'],
  surrealdb: {
    client: {
      endpoint: 'http://localhost:8000',
      connectOptions: {
        namespace: 'my_ns',
        database: 'my_db',
      },
    },
  },
})

Features

  • 🔌 Wraps the official surrealdb.js SDK with auto-imported composables and server utils
  • 🧩 SSR-safe composables: useSurrealQuery, useSurrealSelect, useSurrealAuth, and more — all built on top of Nuxt’s useAsyncData
  • 🖥️ Server utils with per-request session support via useSurreal(event) in Nitro event handlers
  • ⚡️ Embedded engines: run SurrealDB in-process with @surrealdb/wasm (client) or @surrealdb/node (server) for in-memory and local persistent storage
  • 🪝 Lifecycle hooks via surrealHooks for connection setup, authentication, and schema initialization
  • 📦 Auto-import of SurrealDB SDK classes (RecordId, Table, Uuid, etc.) and expression helpers (eq, gt, contains, etc.)
  • 🔧 Full configuration via nuxt.config.ts or environment variables

Composables

Client-side

Composable Description
useSurreal() Get the connected Surreal client
useSurrealAsyncData(cb) Low-level SSR-safe wrapper around useAsyncData
useSurrealQuery(query, bindings?) Execute a SurrealQL query with SSR support
useSurrealSelect(table, builder?) Select records with a builder-pattern API
useSurrealAuth() Get the currently authenticated user info
useSurrealRun(name, args?) Execute a SurrealDB function
useSurrealVersion() Get the SurrealDB server version
useSurrealExport(options?) Export the database
useSurrealImport(input) Import a SurrealQL dump
useSurrealMemory() Access the in-memory WASM client
useSurrealLocal() Access the local WASM client

Server-side

Util Description
useSurreal() / useSurreal(event) Get the remote client or a per-request session
useSurrealMemory() / useSurrealMemory(event) In-memory Node engine (requires @surrealdb/node)
useSurrealLocal() / useSurrealLocal(event) Local persistent Node engine (requires @surrealdb/node)

Environment Variables

Configuration maps to Nuxt runtime config. Override values using env vars:

# Client (public)
NUXT_PUBLIC_SURREALDB_ENDPOINT="http://localhost:8000"
NUXT_PUBLIC_SURREALDB_CONNECT_OPTIONS_NAMESPACE="my_ns"
NUXT_PUBLIC_SURREALDB_CONNECT_OPTIONS_DATABASE="my_db"

# Server-only
NUXT_SURREALDB_ENDPOINT="http://internal-surrealdb:8000"
NUXT_SURREALDB_SESSION="new"
NUXT_SURREALDB_LOCAL_ENDPOINT="surrealkv://./.data/db"

Optional Dependencies

Package Purpose
@surrealdb/wasm Client-side embedded engines (in-memory, IndexedDB)
@surrealdb/node Server-side embedded engines (in-memory, SurrealKV)

[!WARNING]
The IndexedDB (indxdb://) WASM engine is currently bugged upstream. In-memory mode works as expected.

Contribution

Local development 
# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Release new version
pnpm run release
[beta]v0.14.0