Registry / messaging / nuxt-easy-websocket

nuxt-easy-websocket

library4.1.2jsnpmunverified

A Nuxt module for seamless WebSocket integration with type-safe messaging, file-based routing, auto-reconnection, and support for multiple external WebSocket connections. Current stable version is 4.1.2, actively maintained with regular releases. Key differentiators include file-based event routing similar to Nitro Routes, TypeScript-first design with full type inference, and built-in support for both client and server-side handlers within Nuxt 3 projects.

messaging

npm install nuxt-easy-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NUXT-EASY-WEBSOCKE

nuxt-easy-websocket

messagingjavascriptv4.1.2

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.

useWebSocket

✓ const ws = useWebSocket()

✗ import { useWebSocket } from '#easy-websocket'

Auto-imported composable in Nuxt 3; no manual import needed.

defineSocketHandler

✓ export default defineSocketHandler(...)

✗ export default defineEventHandler(...)

Used in server-side socket event handlers (e.g., open.ts, close.ts). Auto-imported.

defineSocketEvent

✓ export default defineSocketEvent(...)

✗ export default defineWebSocketEvent(...)

Used in client-side socket event handlers (e.g., chat.ts). Auto-imported.

Shows basic setup with Nuxt config, client composable usage (send/on events), server-side handler, and client-side event registration.

// nuxt.config.ts export default defineNuxtConfig({ modules: ['nuxt-easy-websocket'], easyWebSocket: { clientSrcDir: 'socket', serverSrcDir: 'socket', ws: { maxReconnectAttempts: 10, reconnectDelay: 5000 } } }) // app/vue (or any component) <script setup lang="ts"> const ws = useWebSocket() // Send a message to server ws.send('chat', { user: 'Alice', text: 'Hello!' }) // Listen for incoming events ws.on('message', (data) => { console.log('Received:', data) }) // Lifecycle ws.onOpen(() => console.log('Connected')) ws.onClose(() => console.log('Disconnected')) </script> // server/socket/api/message.ts export default defineSocketHandler({ handler: (event) => { const data = event.data // Broadcast to all clients event.send({ user: 'Server', text: 'Echo: ' + data.text }) } }) // client/socket/chat.ts (auto-registered for 'chat' events) export default defineSocketEvent({ handler: (data) => { console.log('Chat event:', data) } })

Debug

Known issues

breakingStarting from v4, the module uses Nuxt 3 auto-imports and no longer requires explicit imports. 'useWebSocket', 'defineSocketHandler', and 'defineSocketEvent' are auto-imported. Manual imports from '#easy-websocket' may break.

fix

Remove manual imports; rely on Nuxt 3 auto-imports.

affects: >=4.0.0

breakingFile-based event routing directories changed in v4. Previously used 'websocket' directory; now defaults to 'socket'. Custom directories must be specified in nuxt.config.

fix

Rename directories or set 'clientSrcDir' and 'serverSrcDir' in config.

affects: >=4.0.0

deprecatedThe 'externalSockets' config option is deprecated in v4.1. Use separate WebSocket connections via the 'connect' method instead.

fix

Use 'ws.connect(url, name)' programmatically instead of config.

affects: >=4.1.0

gotchaClient-side event handler files must be placed under 'app/socket/' or a custom clientSrcDir, not in 'server/socket/'. Placing them incorrectly leads to 404 errors.

fix

Ensure client handlers are under 'app/socket/' and server handlers under 'server/socket/'.

affects: >=4.0.0

Errors

Common errors & fixes

Cannot find module '#easy-websocket' or its corresponding type declarations.

Manual import of '#easy-websocket' instead of using auto-imports.

fix

Remove import statement; use composable directly without import.

WebSocket connection failed: Error: connect ECONNREFUSED ::1:3000

Server not running or WebSocket endpoint not configured.

fix

Ensure Nuxt dev server is running and WebSocket is enabled (default). Use correct port.

TypeError: ws.send is not a function

Using 'ws' before Nuxt app is initialized (outside setup).

fix

Only call useWebSocket() inside a component's setup or a composable that runs after app mount.

Upgrade

Version history

4.1.2latest on npm

Audit

Dependencies

nuxtrequiredRequired as a Nuxt module; compatible with Nuxt 3.x

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Bombastickj/nuxt-easy-websocket ↗

packagenuxt-easy-websocket ↗

homepagehttps://github.com/Bombastickj/nuxt-easy-websocket#readme ↗