Registry / web-framework / vite-plugin-vue-server-ref

vite-plugin-vue-server-ref

JSON →
library1.0.0jsnpmunverified

vite-plugin-vue-server-ref is a Vite plugin designed to facilitate the sharing of reactive state between multiple Vue clients and the Vite development server. It enables real-time synchronization of data across browser tabs or different client instances, utilizing Vue's reactivity system. The current stable version is v1.0.0, which notably transitioned to an ESM-only architecture, dropping CommonJS support. The package sees active development with regular updates addressing bug fixes and introducing minor features. Key differentiators include its tight integration with Vite's dev server, the use of virtual module imports (e.g., `server-ref:key`, `server-reactive:key`) for seamless state access, and features like granular synchronization control and incremental updates for reactive objects via diffing.

npm install vite-plugin-vue-server-ref
INSTALL
IMPORT
SIG · VITE-PLUGIN-VUE-SE
V
vite-plugin-vue-server-ref
web-frameworkjavascriptv1.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ServerRef
import ServerRef from 'vite-plugin-vue-server-ref'
const ServerRef = require('vite-plugin-vue-server-ref')
Used for configuring the plugin in `vite.config.ts`. The package is ESM-only since v1.0.0, rendering `require()` incompatible.
server-ref:key
import foo from 'server-ref:foo'
import { foo } from 'server-ref:foo'
This is a virtual module import that provides a Vue `Ref` object, which is treated as a default export.
server-reactive:key
import object from 'server-reactive:object'
import { object } from 'server-reactive:object'
This is a virtual module import for sharing a reactive object, also treated as a default export.
ServerRef (type)
import type { ServerRef, ServerReactive } from 'vite-plugin-vue-server-ref/client'
import { ServerRef, ServerReactive } from 'vite-plugin-vue-server-ref/client'
Essential for providing correct TypeScript type inference for the virtual module imports, which default to `any`. Using `import type` ensures it's stripped from the runtime bundle.

This quickstart demonstrates how to configure `vite-plugin-vue-server-ref` in `vite.config.ts` with initial state and then use `server-ref` and `server-reactive` virtual imports within a Vue component to access and synchronize state across multiple clients and the Vite development server, including type-safety with `import type`.

import { defineConfig } from 'vite'; import ServerRef from 'vite-plugin-vue-server-ref'; import Vue from '@vitejs/plugin-vue'; // vite.config.ts export default defineConfig({ plugins: [ Vue(), ServerRef({ state: { foo: 'bar', object: { count: 0, message: 'Hello' } } }) ] }); // src/main.ts (or a Vue component) import { createApp } from 'vue'; import App from './App.vue'; createApp(App).mount('#app'); // src/App.vue <script setup lang="ts"> import { ref } from 'vue'; import type { ServerReactive, ServerRef } from 'vite-plugin-vue-server-ref/client'; const foo = (await import('server-ref:foo')).default as ServerRef<string>; const object = (await import('server-reactive:object?diff')).default as ServerReactive<{ count: number; message: string }>; console.log('Initial foo:', foo.value); // Should log 'bar' console.log('Initial object:', object.count); // Should log 0 foo.value = 'updated string'; object.count++; object.message = 'World'; // You can also listen for changes from the server/other clients foo.$onSet((newValue) => { console.log(`Foo changed from server/client: ${newValue}`); }); // Example of controlling sync direction // foo.$syncUp = false; // Makes it download-only // object.$syncDown = false; // Makes it upload-only const localCount = ref(0); setInterval(() => { localCount.value++; // This won't sync to server unless foo.$syncUp is true and value is changed // console.log('Local count:', localCount.value); }, 1000); </script> <template> <div> <h1>Server Ref Demo</h1> <p>Foo: {{ foo.value }}</p> <p>Object Count: {{ object.count }}</p> <p>Object Message: {{ object.message }}</p> <p>Local Count: {{ localCount }}</p> </div> </template>
Debug
Known issues
breakingStarting from v1.0.0, vite-plugin-vue-server-ref is exclusively an ESM (ECMAScript Module) package, dropping support for CommonJS. This requires using `import` statements in your `vite.config.ts` and any Node.js files that interact with the plugin.
fix
Ensure your project is configured for ESM, and replace `require()` statements with `import` statements. If using `vite.config.js`, rename it to `vite.config.mjs` or ensure your `package.json` has `"type": "module"`.
affects: >=1.0.0
breakingVersion 0.4.0 also introduced a breaking change by moving to `type: module` in its `package.json`, which affected CommonJS compatibility prior to the full ESM-only transition in v1.0.0.
fix
Similar to v1.0.0, ensure your project's module resolution properly handles ESM packages. For Node.js environments, use `import` syntax or configure transpilation if necessary.
affects: >=0.4.0 <1.0.0
gotchaVirtual module imports like `server-ref:key` and `server-reactive:key` return an `any` type by default in TypeScript. This leads to a lack of type safety when accessing their properties (e.g., `.value` or object keys).
fix
Always use `import type { ServerRef, ServerReactive } from 'vite-plugin-vue-server-ref/client'` and apply type assertions (e.g., `const foo = _foo as ServerRef<string>`) to ensure proper type inference and safety.
affects: >=0.1.0
gotchaWhen working with reactive objects, simply using `server-reactive:key` will send the entire object on every change. For incremental updates (deep diffing), you must append `?diff` to the virtual import path.
fix
For reactive objects where partial updates are desired, change your import from `import object from 'server-reactive:object'` to `import object from 'server-reactive:object?diff'`.
affects: >=0.1.0
gotchaThe plugin exposes `$syncUp` and `$syncDown` properties on the server ref/reactive objects to control synchronization direction. Misunderstanding or misusing these can lead to unexpected behavior where state changes are not propagated.
fix
Understand that `foo.$syncUp = false` means changes made locally *will not* be sent to the server, making it download-only. `foo.$syncDown = false` means changes from the server *will not* be received, making it upload-only (if `$syncUp` is true). Set these flags carefully according to your desired sync behavior.
affects: >=0.1.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to `require()` `vite-plugin-vue-server-ref` in a CommonJS environment after it became ESM-only.
fix
Change `const ServerRef = require('vite-plugin-vue-server-ref')` to `import ServerRef from 'vite-plugin-vue-server-ref'` and ensure your Node.js or Vite configuration supports ESM.
Property 'value' does not exist on type 'ServerRef<any>'
TypeScript's default type inference for virtual modules is `any`, leading to type errors when accessing properties like `.value` or specific keys on a reactive object.
fix
Import the correct types and apply a type assertion: `import type { ServerRef } from 'vite-plugin-vue-server-ref/client'; const foo = _foo as ServerRef<string>;`
Failed to resolve import "server-ref:foo" from "src/App.vue". Does the file exist?
The `vite-plugin-vue-server-ref` plugin is not correctly configured or loaded in `vite.config.ts`, or the Vite dev server is not running.
fix
Verify that `vite-plugin-vue-server-ref` is added to the `plugins` array in your `vite.config.ts`. Ensure your `vite.config.ts` is correctly named and located, and that Vite is running in development mode.
TypeError: Cannot read properties of undefined (reading 'count')
Accessing properties on a `server-reactive` object before it has been properly initialized or before the server has provided its state, or the key does not exist.
fix
Ensure the `state` object in your `vite.config.ts` has the key you are trying to access (e.g., `object.count`). If it's an asynchronous component, ensure proper loading states or fallbacks while the ref is being populated.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
viterequiredPeer dependency for Vite plugin functionality.
vuerequiredPeer dependency for Vue 3 reactivity system integration.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
vite-plugin-vue-server-ref — npm install vite-plugin-vue-server-ref · libregistry