Guide

Configuration

Learn how to configure Nuxt SurrealDB in your Nuxt application

Configuration

All options are set under the surrealdb key in your nuxt.config.ts.

Module options

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-surrealdb'],
  surrealdb: {
    // Auto-import SurrealDB SDK classes (RecordId, Table, etc.)
    autoImport: true, // default

    // Also auto-import expression helpers (eq, gt, contains, etc.)
    autoImportExpressions: false, // default

    // Disable WASM engine even if @surrealdb/wasm is installed
    disableWasmEngine: false, // default

    // Disable Node engine even if @surrealdb/node is installed
    disableNodeEngine: false, // default

    client: { /* ... */ },
    server: { /* ... */ },
  },
})

Client configuration

The client key configures the SurrealDB connection used in the browser (and during SSR for data fetching). It maps to runtimeConfig.public.surrealdb.

nuxt.config.ts

export default defineNuxtConfig({
  surrealdb: {
    client: {
      // Remote SurrealDB endpoint
      endpoint: 'http://localhost:8000',

      // Connection options (namespace, database, auth, etc.)
      connectOptions: {
        namespace: 'my_ns',
        database: 'my_db',
        authentication: {
          username: 'root',
          password: 'root',
        },
      },

      // Prefer HTTP over WebSockets during SSR (default: true)
      preferHttp: true,

      // Auto-connect on first use (default: true)
      autoConnect: true,
    },
  },
})

Server configuration

The server key configures the SurrealDB connection used exclusively on the server (Nitro). It maps to runtimeConfig.surrealdb and is never exposed to the client.

nuxt.config.ts

export default defineNuxtConfig({
  surrealdb: {
    server: {
      // Prefer HTTP over WebSockets (default: true)
      preferHttp: true,

      // Auto-connect on first use (default: true)
      autoConnect: true,

      // Session mode when passing H3Event: 'new' or 'fork'
      session: 'new', // default
    },
  },
})

session: 'new' creates a fresh session per request, while session: 'fork' forks from the existing connection. Use 'new' for per-request isolation.

When server options are not explicitly set, the composable merges the server config with the public client config, so you don't need to repeat shared values like endpoint.

Embedded engines

In-memory database

To use an in-memory SurrealDB instance (no persistence), configure the memory key:

nuxt.config.ts

export default defineNuxtConfig({
  surrealdb: {
    // Client-side (requires @surrealdb/wasm)
    client: {
      memory: {
        connectOptions: {
          namespace: 'my_ns',
          database: 'my_db',
        },
      },
    },
    // Server-side (requires @surrealdb/node)
    server: {
      memory: {
        session: 'new',
        connectOptions: {
          namespace: 'my_ns',
          database: 'my_db',
        },
      },
    },
  },
})

Local persistent database

For a locally persisted embedded database, configure the local key:

nuxt.config.ts

export default defineNuxtConfig({
  surrealdb: {
    // Server-side with SurrealKV (requires @surrealdb/node)
    server: {
      local: {
        endpoint: 'surrealkv://./.data/db',
        session: 'new',
        connectOptions: {
          namespace: 'my_ns',
          database: 'my_db',
        },
      },
    },
  },
})

The IndexedDB (indxdb://) WASM engine is currently not fully supported with SurrealDB 3.0. In-memory (mem://) mode works as expected.

Environment variables

Since configuration maps to Nuxt runtime config, you can override all values using environment variables.

Client (public) variables

# Remote endpoint
NUXT_PUBLIC_SURREALDB_ENDPOINT="http://localhost:8000"

# Connection options
NUXT_PUBLIC_SURREALDB_CONNECT_OPTIONS_NAMESPACE="my_ns"
NUXT_PUBLIC_SURREALDB_CONNECT_OPTIONS_DATABASE="my_db"

# Prefer HTTP over WS
NUXT_PUBLIC_SURREALDB_PREFER_HTTP="true"

# Auto-connect
NUXT_PUBLIC_SURREALDB_AUTO_CONNECT="true"

Server-only variables

# Server endpoint (overrides public endpoint for server-side)
NUXT_SURREALDB_ENDPOINT="http://internal-surrealdb:8000"

# Server session mode
NUXT_SURREALDB_SESSION="new"

# Server local engine endpoint
NUXT_SURREALDB_LOCAL_ENDPOINT="surrealkv://./.data/db"

# Server memory connection options
NUXT_SURREALDB_MEMORY_CONNECT_OPTIONS_NAMESPACE="my_ns"
NUXT_SURREALDB_MEMORY_CONNECT_OPTIONS_DATABASE="my_db"

Using environment variables is the recommended way to handle credentials and environment-specific endpoints without hardcoding them in nuxt.config.ts. For example, use $development and $production overrides combined with .env files:

nuxt.config.ts

export default defineNuxtConfig({
  surrealdb: {
    client: {
      endpoint: '', // set via NUXT_PUBLIC_SURREALDB_ENDPOINT
      connectOptions: {
        namespace: '',
        database: '',
      },
    },
  },
  $development: {
    surrealdb: {
      client: {
        endpoint: 'http://localhost:8000',
      },
    },
  },
})

Auto-imports

When autoImport is enabled (default), the following classes from the surrealdb SDK are auto-imported in both app and server contexts:

Uuid, RecordId, StringRecordId, RecordIdRange
BoundIncluded, BoundExcluded
Duration, Decimal, Table
Geometry, GeometryPoint, GeometryLine, GeometryPolygon
GeometryMultiPoint, GeometryMultiLine, GeometryMultiPolygon, GeometryCollection
Surreal

When autoImportExpressions is also enabled, the following expression helpers are auto-imported:

expr, raw
eq, eeq, gt, gte, lt, lte
contains, containsAll, containsAny, containsNone
inside, outside, intersects
matches, knn, between
and, or, not

Installation

Learn how to install Nuxt SurrealDB in your Nuxt application

Hooks

Learn how to use lifecycle hooks to customize SurrealDB connections