Quickstart

Getting started with @nhtio/vue-re-active-record is quick and easy. Just follow the steps below and you'll be up and running in no time.

Installation

You can install @nhtio/vue-re-active-record directly from your preferred package manager

npm

npm i @nhtio/vue-re-active-record

pnpm

pnpm add @nhtio/vue-re-active-record

yarn

yarn add @nhtio/vue-re-active-record

The @nhtio/vue-re-active-record plugin wraps the underlying ReActiveRecord library for seamless Vue integration. Your configuration should conform to ReactiveDatabaseOptions from ReActiveRecord, except the hooks property is managed internally by the plugin and must not be set manually.

Basic Plugin Setup

To use the plugin, import VueReActiveRecord from @nhtio/vue-re-active-record and provide configuration options:

import { createApp } from 'vue'
import VueReActiveRecord from '@nhtio/vue-re-active-record'

const app = createApp(App)
app.use(VueReActiveRecord, {
  namespace: 'my-app',
  version: 1,
  psk: 'your-pre-shared-key-at-least-16-chars',
  models: {
    task: {
      schema: '++id, completed, priority, title',
      properties: ['id', 'title', 'completed', 'priority'],
      primaryKey: 'id',
    },
  },
})

Configuration Options

Option	Type	Required	Description
namespace	string	Yes	The IndexedDB database namespace (database name).
version	number	Yes	Database schema version; increment this number to trigger migrations.
psk	string	Yes	Pre-shared key for encryption and synchronization (minimum length enforced).
models	Record<string, ModelConfig>	Yes	Object describing models and their schemas, including schema, properties, primaryKey, and relationships.

More Info

You can learn more about these options in the ReActiveRecord Configuration Guide.

Vue Plugin Installation Options

When installing the Vue plugin, you can provide an optional third parameter with these options:

Option	Type	Default	Description
useOptionsAPI	boolean	false	Enables Options API support (adds global mixins for this.$reActiveDatabase).
useDevTools	boolean	true	Enables integration with Vue DevTools for inspecting reactive models and queries.

Type Augmentation

To ensure proper TypeScript support for your models, extend the VueReActiveRecordTypes interface in your app’s types:

declare module '@nhtio/vue-re-active-record' {
  interface VueReActiveRecordTypes {
    ObjectMap: {
      task: {
        id: number
        title: string
        completed: boolean
        priority: number
      }
    }
  }
}

This lets helper functions like useReActiveModel infer correct typings.

Next Steps

Once your configuration is in place, you can begin querying and using models in your Vue components.

Hydration & SSR Safety

For hydration and SSR safety, always use the onReActiveDatabaseReady composable to run any queries or mutations in your Vue components. This ensures your code only runs after the real database is ready in the browser, and is a no-op in SSR (where stub data is used).

import { ref } from 'vue'
import { useReActiveModel, onReActiveDatabaseReady } from '@nhtio/vue-re-active-record'

const Task = useReActiveModel('task')
const tasks = ref([])

onReActiveDatabaseReady(async () => {
  tasks.value = await Task.all()
})

See the Example Implementation for a real-world example that demonstrates both configuration and component usage.