Nuxt SurrealDB

A Nuxt module aimed to simplify the use of SurrealDB.

• ✨  Release Notes

WIP

This module is still under development and not suitable for production use, proceed at your own risk. Expect breaking changes! There are no docs atm, so please refer to the playground or the source code.

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add nuxt-surrealdb

That's it! You can now edit your default Database Preset and use Nuxt SurrealDB in your Nuxt app ✨

Features

• 🚀 Custom built-in $surrealFetch and useSurrealFetch (based on $fetch and useFetch respectively).
• 📦 Custom Database Presets, to be able to use multiple Databases on a composable/per-function basis.
• ⚡️ Built-in support for RPC endpoint via $surrealRPC and useSurrealRPC.
• 🏗️ Built-in Nuxt server useSurrealRPC util with server-side private DB Presets for a private network communication with SurrealDB.
• 💡 Each RPC method is mapped to a useSurrealDB exported function.
• 🌟 Built-in support for Websocket communication with RPC methods using the useSurrealWS composable.

Database Presets

It is possible to customize the default preset or define your own Database presets either via nuxt.config.ts or via .env.

!NOTE When passing variables to a custom preset like production below, it is important to initialize it as an empty object inside nuxt.config.ts

NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_HOST="https://example.com"
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_WS="wss://example.com"
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_NS="surrealdb"
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_DB="docs"
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_SC="user"

# For auth
# user and pass separated by a colon
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_AUTH="root:root"
# Or as a Bearer
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_AUTH="Bearer mySuperLongBearerToken"
# Or as an object
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_AUTH_USER="root"
NUXT_PUBLIC_SURREALDB_DATABASES_PRODUCTION_AUTH_PASS="root"

export default defineNuxtConfig({
  modules: ['nuxt-surrealdb'],
  surrealdb: {
    databases: {
      staging: {
        host: 'https://staging.example.com',
        ws: 'wss://staging.example.com',
        NS: 'staging',
        DB: 'demo',

        // Auth examples
        auth: 'root:root',
        auth: 'Bearer mySuperLongBearerToken',
        auth: {
          user: 'root',
          pass: 'root'
        }
      },
      production: {
        host: '', // initialize any property that will be set via `.env`
        ws: '',
        NS: '',
        DB: ''
      },
    },
    server: {
      databases: {
        production: {
          auth: '', // NUXT_SURREALDB_DATABASES_PRODUCTION_AUTH='root:root'
        }
      }
    }
  },
  // ...
})

It is also possible to expand or change database properties (like server.databases.production.auth above) to be available only on Nuxt server-side. This becomes particularly useful for a more traditional database auth approach without exposing credentials client-side or to use a different host address in a private network.

RPC functions

The main useSurrealDB exports a number of functions that directly communicate with the RPC endpoint. Each function has two variants, one starts with $ and one without. The first is based on $surrealRPC, that provides the plain function, while the latter uses useSurrealRPC, taking advantage of useSurrealFetch (and thus, useFetch).

Here the full list:

const {
  authenticate, // $authenticate
  create,       // $create
  info,         // $info
  insert,       // $insert
  invalidate,   // $invalidate
  merge,        // $merge
  patch,        // $patch
  query,        // $query
  remove,       // $remove
  select,       // $select
  signin,       // $signin
  signup,       // $signup
  sql,          // $sql
  update,       // $update
  version,      // $version
} = useSurrealDB()

!NOTE sql function is an alias for query while version uses its HTTP endpoint.

RPC Websocket

The useSurrealWS composable exposes a Websocket connection to handle live communication with SurrealDB. It uses useWebsocket from @vueuse/core under the hood, this means that SSR, auto-connect and auto-disconnect are handled automatically by default. Data is Automatically parsed from JSON to string both in input as well in data return. If available, upon Websocket connection, it will any Auth token from a prior user login. Database Presets and Websocket options are available as main arguments of the composable.

Below a list of the main functions available from the Websocket composable:

const {
  authenticate,
  close,
  create,
  data,
  define,  // Surreal's `let`
  info,
  insert,
  invalidate,
  kill,
  live,
  merge,
  open,
  patch,
  query,
  remove,
  rpc,
  select,
  send,
  signin,
  signup,
  sql,     // alias for query
  status,
  unset,
  update,
  use,
  ws,
} = useSurrealWS()

!WARNING Currently while the signin and signup functions are avaible, they are limited to that Websocket connection. Therefore if auth is required outside of that websocket connection it is advised to use the main useSurrealAuth composable for SCOPE user authentication.

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release