README.md

Nuxt SurrealDB

A Nuxt module aimed to simplify the use of SurrealDB.

• ✨  Release Notes
• 📖  Documentation

Quick Setup

Install the module to your Nuxt application:

npx nuxi module add nuxt-surrealdb

Then edit your default Database Preset and use Nuxt SurrealDB in your Nuxt app ✨

Features

• 📦 Custom Database Presets, to be able to use multiple Databases on a composable/per-function basis.
• 🚀 Custom built-in $surrealFetch and useSurrealFetch, based on $fetch and useFetch respectively.
• ⚡️ 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 Websockets 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 shop below, it is important to initialize it as an empty object inside nuxt.config.ts

NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_HOST="https://example.com"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_WS="wss://example.com"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_NS="surrealdb"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_DB="docs"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_SC="user"

# To add authentication server side (this does not override the client's token)
# As a Bearer
NUXT_SURREALDB_DATABASES_SHOP_AUTH="mySuperLongBearerToken"
# Or as an object
NUXT_SURREALDB_DATABASES_SHOP_AUTH_USER="root"
NUXT_SURREALDB_DATABASES_SHOP_AUTH_PASS="root"

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

      crm: {
        host: 'https://crm.example.com',
        ws: 'wss://crm.example.com',
        NS: 'demo',
        DB: 'crm',
        // The following auth example is exposed client side!
        auth: 'mySuperLongBearerToken'
      },

      shop: {},
    },
    server: { // the following add auth only server side
      databases: {
        default: {
          auth: '', // then edit it via NUXT_SURREALDB_DATABASES_DEFAULT_AUTH
          // OR
          auth: {
            user: '', // then edit it via NUXT_SURREALDB_DATABASES_DEFAULT_AUTH_USER
            pass: '' // then edit it via NUXT_SURREALDB_DATABASES_DEFAULT_AUTH_PASS
          }
        }
      }
    }
  },
  // To change a db preset during development it is best to do the following
  $development: {
    surrealdb: {
      databases: {
        default: {
          host: 'http://localhost:8000',
          ws: 'ws://localhost:8000'
        }
      }
    }
  },
  // ...
})

Note

If you want to use different db preset between development and production, please use Nuxt's native $development and $production properties within your nuxt.config.ts like in the example above.

It is also possible to expand or change database properties server-side (like surrealdb.server.databases.default.auth above). 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.

Then, to use a database preset, you just have to set it within the last parameter of each main composable (functions destructured from useSurrealDB also support this override).

// all the functions destructured will be executed against the CRM database
const { query, select } = useSurrealDB({
  database: 'crm',
})

// only the following select will be made against the default database
const { data } = await select('products', {
  database: 'default',
})

// you could also define a one-time only preset
const { data } = await sql(
  'SELECT * FROM products WHERE price < $maxPrice;',
  { maxPrice: 500 },
  {
    database: {
      host: 'https://surrealdb.example.com',
      NS: 'demo',
      DB: 'shop',
    },
  },
)

RPC Methods

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
  delete,       // $delete
  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 method 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 methods available from the Websocket composable:

const {
  authenticate,
  close,
  create,
  data,
  set,      // alias for `let`
  info,
  insert,
  invalidate,
  kill,
  let,
  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 methods are avaible, they are limited to the current 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

Local development

# 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