nuxt-surrealdb

A Nuxt module aimed to simplify the use of SurrealDB

Nuxt SurrealDB

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