{"id":48796,"library":"nuxt-easy-websocket","title":"nuxt-easy-websocket","description":"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.","status":"active","version":"4.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/Bombastickj/nuxt-easy-websocket","tags":["javascript"],"install":[{"cmd":"npm install nuxt-easy-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-easy-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-easy-websocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a Nuxt module; compatible with Nuxt 3.x","package":"nuxt","optional":false}],"imports":[{"note":"Auto-imported composable in Nuxt 3; no manual import needed.","wrong":"import { useWebSocket } from '#easy-websocket'","symbol":"useWebSocket","correct":"const ws = useWebSocket()"},{"note":"Used in server-side socket event handlers (e.g., open.ts, close.ts). Auto-imported.","wrong":"export default defineEventHandler(...)","symbol":"defineSocketHandler","correct":"export default defineSocketHandler(...)"},{"note":"Used in client-side socket event handlers (e.g., chat.ts). Auto-imported.","wrong":"export default defineWebSocketEvent(...)","symbol":"defineSocketEvent","correct":"export default defineSocketEvent(...)"}],"quickstart":{"code":"// nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: ['nuxt-easy-websocket'],\n  easyWebSocket: {\n    clientSrcDir: 'socket',\n    serverSrcDir: 'socket',\n    ws: {\n      maxReconnectAttempts: 10,\n      reconnectDelay: 5000\n    }\n  }\n})\n\n// app/vue (or any component)\n<script setup lang=\"ts\">\nconst ws = useWebSocket()\n\n// Send a message to server\nws.send('chat', { user: 'Alice', text: 'Hello!' })\n\n// Listen for incoming events\nws.on('message', (data) => {\n  console.log('Received:', data)\n})\n\n// Lifecycle\nws.onOpen(() => console.log('Connected'))\nws.onClose(() => console.log('Disconnected'))\n</script>\n\n// server/socket/api/message.ts\nexport default defineSocketHandler({\n  handler: (event) => {\n    const data = event.data\n    // Broadcast to all clients\n    event.send({ user: 'Server', text: 'Echo: ' + data.text })\n  }\n})\n\n// client/socket/chat.ts (auto-registered for 'chat' events)\nexport default defineSocketEvent({\n  handler: (data) => {\n    console.log('Chat event:', data)\n  }\n})","lang":"typescript","description":"Shows basic setup with Nuxt config, client composable usage (send/on events), server-side handler, and client-side event registration."},"warnings":[{"fix":"Remove manual imports; rely on Nuxt 3 auto-imports.","message":"Starting 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Rename directories or set 'clientSrcDir' and 'serverSrcDir' in config.","message":"File-based event routing directories changed in v4. Previously used 'websocket' directory; now defaults to 'socket'. Custom directories must be specified in nuxt.config.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use 'ws.connect(url, name)' programmatically instead of config.","message":"The 'externalSockets' config option is deprecated in v4.1. Use separate WebSocket connections via the 'connect' method instead.","severity":"deprecated","affected_versions":">=4.1.0"},{"fix":"Ensure client handlers are under 'app/socket/' and server handlers under 'server/socket/'.","message":"Client-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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"search_vec":"'3':76 '4.1.2':35 'activ':36 'auto':22 'auto-reconnect':21 'base':19,46 'built':63 'built-in':62 'client':68 'connect':30 'current':31 'design':56 'differenti':42 'easi':3 'event':47 'extern':28 'file':18,45 'file-bas':17,44 'first':55 'full':58 'handler':73 'includ':43 'infer':60 'integr':11 'javascript':78 'key':41 'maintain':37 'messag':16 'modul':7 'multipl':27 'nitro':51 'nuxt':2,6,75 'nuxt-easy-websocket':1 'project':77 'reconnect':23 'regular':39 'releas':40 'rout':20,48,52 'safe':15 'seamless':9 'server':71 'server-sid':70 'side':72 'similar':49 'stabl':32 'support':25,65 'type':14,59 'type-saf':13 'typescript':54 'typescript-first':53 'version':33 'websocket':4,10,29 'within':74","created_at":"2026-06-07T16:58:30.847736+00:00","updated_at":"2026-06-07T16:58:30.847736+00:00","problems":[{"fix":"Remove import statement; use composable directly without import.","cause":"Manual import of '#easy-websocket' instead of using auto-imports.","error":"Cannot find module '#easy-websocket' or its corresponding type declarations."},{"fix":"Ensure Nuxt dev server is running and WebSocket is enabled (default). Use correct port.","cause":"Server not running or WebSocket endpoint not configured.","error":"WebSocket connection failed: Error: connect ECONNREFUSED ::1:3000"},{"fix":"Only call useWebSocket() inside a component's setup or a composable that runs after app mount.","cause":"Using 'ws' before Nuxt app is initialized (outside setup).","error":"TypeError: ws.send is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/Bombastickj/nuxt-easy-websocket#readme","github":"https://github.com/Bombastickj/nuxt-easy-websocket","docs":null,"changelog":null,"pypi":null,"npm":"nuxt-easy-websocket","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}