Vite Plugin for Vue Server-Side State Synchronization

Common errors

• ERR_REQUIRE_ESM

  cause 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>'

  cause 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?

  cause 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')

  cause 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.

Warnings

• breaking Starting 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"`.
• breaking Version 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.
• gotcha Virtual 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.
• gotcha When 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'`.
• gotcha The 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.

Install

• npm install vite-plugin-vue-server-ref npm
• yarn add vite-plugin-vue-server-ref yarn
• pnpm add vite-plugin-vue-server-ref pnpm

Imports

• ServerRef
  wrong:

  const ServerRef = require('vite-plugin-vue-server-ref')

  correct:

  import ServerRef from '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
  wrong:

  import { foo } from 'server-ref:foo'

  correct:

  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
  wrong:

  import { object } from 'server-reactive:object'

  correct:

  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)
  wrong:

  import { ServerRef, ServerReactive } from 'vite-plugin-vue-server-ref/client'

  correct:

  import type { 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.

Quickstart

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>