Quick Start with Vue 3.2+
The @pravosleva/reactive-engine/vue adapter connects the core reactive graph to Vue 3's reactivity system via the extended ReactiveEngine (engine.use(...)) or the useReactiveValue(...) composable. It returns a strictly typed ShallowRef<T> and automatically unsubscribes on component unmount via onScopeDispose.
Installation
yarn add @pravosleva/reactive-engineBasic Example: Counter
<script setup lang="ts">
import { AbstractService } from '@pravosleva/reactive-engine'
import { ReactiveEngine } from '@pravosleva/reactive-engine/vue'
class CounterLogic extends AbstractService {
public counter = this.engine.signal<number>(0, 'vue-example:counter')
public doubled = this.engine.computed(() => this.counter.value * 2, 'vue-example:doubled')
public inc = () => {
this.counter.value += 1
}
}
const engine = new ReactiveEngine()
const logic = engine.inject(CounterLogic)
// Returns ShallowRef<number>, automatically cleaned up via onScopeDispose
const counter = engine.use(logic.counter)
const doubled = engine.use(logic.doubled)
</script>
<template>
<div>
<h3>Vue 3 Signal Example</h3>
<p>
Counter: <code>{{ counter }}</code> (x2: <code>{{ doubled }}</code>)
</p>
<button type="button" @click="logic.inc">
+ INC
</button>
</div>
</template>Working with Proxy Collections (reactive) & resource
The adapter tracks deep Proxy arrays and objects (engine.reactive()), creating a shallow reference copy on .push() / .splice() mutations so Vue 3 templates re-render instantaneously without deep double-proxying:
<script setup lang="ts">
import { AbstractService } from '@pravosleva/reactive-engine'
import { ReactiveEngine, useReactiveValue } from '@pravosleva/reactive-engine/vue'
class CartService extends AbstractService {
public items = this.engine.reactive<string[]>(['Laptop'], 'vue:cart')
public addItem(name: string) {
this.items.push(name)
}
}
const engine = new ReactiveEngine()
const cart = engine.inject(CartService)
// You can use either engine.use(cart.items) or useReactiveValue(cart.items)
const items = useReactiveValue(cart.items)
</script>
<template>
<div>
<button type="button" @click="cart.addItem('Monitor')">
Add Item
</button>
<ul>
<li v-for="(item, idx) in items" :key="idx">
{{ item }}
</li>
</ul>
</div>
</template>SSR & API Data Hydration (Nuxt 3 onServerPrefetch + useState)
In Nuxt 3 and other Vue 3 SSR setups, never instantiate const engine = new ReactiveEngine() at module top-level outside setup()—doing so leaks state across concurrent server requests from different users.
The recommended Nuxt 3 pattern combines:
- Per-request engine isolation inside
<script setup>(or a per-request Nuxt plugin). - Nuxt's serializable
useState('ssr:article'): Automatically serializes server state into the HTML payload and restores it on the client. onServerPrefetch: Awaits API data fetching during server rendering and writes the snapshot intouseState.
Step 1. Service with Hydration Support (ArticleService.ts)
import { AbstractService } from '@pravosleva/reactive-engine'
export interface ArticleDto {
id: string
title: string
content: string
}
export class ArticleService extends AbstractService {
public article = this.engine.signal<ArticleDto | null>(null, 'nuxt:article')
public isLoading = this.engine.signal(false, 'nuxt:isLoading')
public error = this.engine.signal<string | null>(null, 'nuxt:error')
public async loadArticle(id: string): Promise<ArticleDto | null> {
this.isLoading.value = true
this.error.value = null
try {
const res = await fetch(`https://example.com{encodeURIComponent(id)}`)
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const data: ArticleDto = await res.json()
this.article.value = data
return data
} catch (err: unknown) {
this.error.value = err instanceof Error ? err.message : 'Failed to load article'
return null
} finally {
this.isLoading.value = false
}
}
public hydrate(snapshot: ArticleDto | null) {
if (snapshot) {
this.article.value = snapshot
}
}
}Step 2. Nuxt 3 Page Component (pages/articles/[id].vue)
<script setup lang="ts">
import { onServerPrefetch, onMounted } from 'vue'
import { ReactiveEngine } from '@pravosleva/reactive-engine/vue'
import { ArticleService, type ArticleDto } from '~/services/ArticleService'
const route = useRoute()
const articleId = String(route.params.id)
// 1. Create an isolated engine instance scoped strictly to the current request/setup
const engine = new ReactiveEngine()
const service = engine.inject(ArticleService)
// 2. Nuxt's useState transfers the serialized payload from server to client
const ssrSnapshot = useState<ArticleDto | null>(`article:${articleId}`, () => null)
// 3. On the client, hydrate the signal synchronously before the first template render
if (ssrSnapshot.value) {
service.hydrate(ssrSnapshot.value)
}
// 4. On the server, await the API fetch and store the snapshot in useState
onServerPrefetch(async () => {
const loaded = await service.loadArticle(articleId)
ssrSnapshot.value = loaded
})
// 5. On client-side SPA navigation, fetch only if no matching snapshot exists
onMounted(() => {
if (service.article.value?.id !== articleId) {
void service.loadArticle(articleId)
}
})
// Bind Vue 3 template to the service signals
const article = engine.use(service.article)
const isLoading = engine.use(service.isLoading)
const error = engine.use(service.error)
</script>
<template>
<div>
<p v-if="isLoading && !article">Loading article...</p>
<p v-else-if="error">Error: {{ error }}</p>
<article v-else-if="article">
<h1>{{ article.title }}</h1>
<p>{{ article.content }}</p>
</article>
</div>
</template>Adapter Key Highlights
ShallowRefinstead of deepref: The adapter intentionally returns aShallowRefso Vue 3 does not wrap core state inside a second layer ofProxyobjects or spend CPU recursively traversing large structures.- Automatic cleanup via
onScopeDispose: Core subscriptions are removed automatically when the component unmounts or itseffectScope()stops.