vue3-websocket

library2.2.0jsnpmunverified

A lightweight Vue 3 plugin for integrating WebSocket connections using the Composition API. Current stable version 2.2.0 (released 2023-09). Provides both a plugin (Vue3Websocket) and composable (useWebSocket) for reactive WebSocket communication. Key differentiator: designed specifically for Vue 3's Composition API with automatic lifecycle management and reactive state. Unlike generic WebSocket wrappers, it handles reconnection, message handling as reactive data, and integrates seamlessly with Vue's reactivity system. Released under MIT, maintained by a solo developer with monthly updates. Supports TypeScript out of the box.

messaging

npm install vue3-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE3-WEBSOCKET

vue3-websocket

messagingjavascriptv2.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Vue3Websocket

✓ import { Vue3Websocket } from 'vue3-websocket'

✗ import Vue3Websocket from 'vue3-websocket'

Requires named import for the plugin (default export is not available).

useWebSocket

✓ import { useWebSocket } from 'vue3-websocket'

✗ const { useWebSocket } = require('vue3-websocket')

ESM only; CommonJS require is not supported.

WebSocketStatus

✓ import { WebSocketStatus } from 'vue3-websocket'

TypeScript type export for connection status enum (CONNECTING, OPEN, CLOSING, CLOSED).

UseWebSocketOptions

✓ import type { UseWebSocketOptions } from 'vue3-websocket'

✗ import { UseWebSocketOptions } from 'vue3-websocket'

Use 'import type' for type-only imports in TypeScript to avoid runtime errors.

Registers the WebSocket plugin globally with reconnection and heartbeat, then uses the composable to send messages and reactively receive data.

import { createApp } from 'vue'; import { Vue3Websocket, useWebSocket } from 'vue3-websocket'; const app = createApp(App); app.use(Vue3Websocket, { url: 'ws://localhost:8080', options: { reconnection: true, reconnectionAttempts: 5, reconnectionDelay: 3000, heartbeat: { enabled: true, interval: 30000, message: 'ping' } } }); app.mount('#app'); // In a component: const { status, data, send, close } = useWebSocket(); // Send message send(JSON.stringify({ action: 'subscribe', channel: 'chat' })); // Reactive data updates when message received console.log(data.value); // Connection status if (status.value === 'OPEN') { console.log('Connected'); }

Debug

Known issues

breakingv2.x removed the old Options API integration and default export. Only Composition API and named exports are supported.

fix

Use named imports: import { Vue3Websocket, useWebSocket } from 'vue3-websocket'

affects: >=2.0.0

gotchaIf you don't call app.use(Vue3Websocket, { url: ... }), useWebSocket will throw an error because it needs the global plugin configuration.

fix

Always register the plugin with app.use() before using useWebSocket.

affects: >=2.0.0

deprecatedOptions like 'reconnectInterval' were renamed to 'reconnectionDelay' in v2.0.0.

fix

Use 'reconnectionDelay' instead of 'reconnectInterval'.

affects: >=2.0.0

gotchaThe 'options' object in app.use doesn't support nested 'url' inside 'options'; url must be at the top level.

fix

Pass url as a separate property: { url: '...', options: { ... } }

affects: >=2.0.0

gotchaUsing 'useWebSocket' without a preceding plugin registration or within a component outside the app tree will cause a silent failure or undefined behavior.

fix

Ensure the composable is called inside a component that is a descendant of the app root.

affects: >=2.0.0

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'url')

Vue3Websocket plugin not registered or url not provided in plugin options.

fix

Add app.use(Vue3Websocket, { url: 'ws://yourserver' }) in main.js.

Uncaught TypeError: vue3_websocket__WEBPACK_IMPORTED_MODULE_0__.useWebSocket is not a function

Using default import instead of named import for useWebSocket.

fix

Use import { useWebSocket } from 'vue3-websocket'.

vue3-websocket: WebSocket connection failed to connect: The URL '...' is invalid.

Invalid WebSocket URL (e.g., missing protocol or incorrect host).

fix

Ensure URL starts with 'ws://' or 'wss://' and is correctly formatted.

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'send')

useWebSocket returned undefined or send method not available (connection not established).

fix

Check that the WebSocket is open before calling send; wait for status.value === 'OPEN'.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

vuerequiredpeer dependency required for plugin and composable to work with Vue 3 reactivity system

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/muzychenka/vue3-websocket ↗

packagevue3-websocket ↗

homepagehttps://github.com/muzychenka/vue3-websocket ↗