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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createRPCServer
✓ import { createRPCServer } from 'vite-dev-rpc'
✗ const { createRPCServer } = require('vite-dev-rpc')
ESM-only package, CommonJS require is not supported. Use named import for server-side RPC setup in Vite plugins.
createRPCClient
✓ import { createRPCClient } from 'vite-dev-rpc'
✗ import createRPCClient from 'vite-dev-rpc'
ESM-only. This function is typically used in client-side code to connect to the RPC server exposed by the Vite plugin. It is a named export.
ViteDevRpcOptions
✓ import type { ViteDevRpcOptions } from 'vite-dev-rpc'
TypeScript type import for configuring the RPC client or server. Always use `import type`.
This quickstart demonstrates how to set up a `vite-dev-rpc` server within a Vite plugin and establish a client connection from the browser, allowing remote procedure calls for `multiply` and `greet` methods.
import { defineConfig } from 'vite';
import { createRPCServer, createRPCClient } from 'vite-dev-rpc';
// --- Vite Plugin (Server-side) ---
const myVitePlugin = () => {
const rpc = createRPCServer('my-rpc-channel', {
multiply(a: number, b: number) {
console.log('Server received multiplication request');
return a * b;
},
greet(name: string) {
console.log('Server received greeting request');
return `Hello, ${name} from Vite server!`;
},
});
return {
name: 'my-rpc-plugin',
configureServer(server) {
server.ws.on('connection', (socket) => {
// Expose RPC methods to the client via Vite's WebSocket
rpc.update(socket);
});
},
// In case you need to send messages from server to client
// You can access rpc.send() or rpc.broadcast() here or from a configured client
};
};
export default defineConfig({
plugins: [myVitePlugin()],
});
// --- Client-side (e.g., in a .js or .ts file loaded by Vite) ---
async function setupClientRPC() {
// Ensure import.meta.hot is available
if (import.meta.hot) {
const clientRpc = createRPCClient<typeof serverMethods>('my-rpc-channel', import.meta.hot);
try {
const result = await clientRpc.multiply(5, 7);
console.log('Client received multiplication result:', result); // Expected: 35
const greeting = await clientRpc.greet('Vite User');
console.log('Client received greeting:', greeting); // Expected: "Hello, Vite User from Vite server!"
} catch (error) {
console.error('RPC client error:', error);
}
} else {
console.warn('Vite HMR is not available, RPC client cannot be initialized.');
}
}
// Define types for server methods for client-side type safety
interface serverMethods {
multiply(a: number, b: number): number;
greet(name: string): string;
}
setupClientRPC();
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'on') or 'send'
The `createRPCServer` or `createRPCClient` is not correctly initialized with the Vite WebSocket server or `import.meta.hot` context, or the `vite` peer dependency is incompatible.
fixVerify that `server.ws` (for `createRPCServer`) or `import.meta.hot` (for `createRPCClient`) is correctly passed and that your `vite` version satisfies `vite-dev-rpc`'s peer dependency requirements.
Error: [vite-dev-rpc] Channel "my-channel" is already registered. Make sure you use unique channel names.
Attempting to create multiple RPC servers or clients with the same channel name in the same context, leading to a naming collision.
fixEnsure each `createRPCServer` and `createRPCClient` pair uses a unique `channel` string identifier across your application to prevent conflicts.
RPC Client error: TypeError: rpcMethod is not a function
The client attempted to call an RPC method that was not defined or properly exposed by the RPC server, or there's a type mismatch in the method signature.
fixDouble-check that the method name exists on the server-side RPC definition (`createRPCServer` methods object) and that the client is calling it with the correct arguments and type signature.
Audit
Dependencies
viterequiredPeer dependency for Vite plugin functionality and HMR context.