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.
defineRouter
✓ import { defineRouter } from 'bun-ws-router'
✗ const { defineRouter } = require('bun-ws-router')
ESM-only; CommonJS require() fails because package is type:module
WebSocketRouter
✓ import type { WebSocketRouter } from 'bun-ws-router'
✗ import { WebSocketRouter } from 'bun-ws-router'
Use 'import type' for type-only imports to avoid runtime side effects
createRouter (default)
✓ import createRouter from 'bun-ws-router'
✗ import { createRouter } from 'bun-ws-router'
createRouter is the default export, not a named export. Check v0.5+ for renamed default
Creates a WebSocket server with message validation using Zod and pub/sub to 'chat' channel.
import { defineRouter } from 'bun-ws-router';
import { z } from 'zod';
const router = defineRouter({
open: (ws) => { ws.subscribe('chat'); },
message: (ws, message) => {
const schema = z.object({ text: z.string() });
const parsed = schema.parse(JSON.parse(message.data));
ws.publish('chat', parsed.text);
},
close: (ws) => { ws.unsubscribe('chat'); },
});
Bun.serve({
port: 3000,
fetch(req, server) {
if (server.upgrade(req)) return undefined;
return new Response('Hello!');
},
websocket: router,
});
console.log('Server running on ws://localhost:3000');
Errors
Common errors & fixes
Error: The module's source code could not be parsed. Are you using a normal import or a re-export?
Using CommonJS `require()` on an ESM-only package
fixUse `import` syntax instead of `require()`
TypeError: server.upgrade is not a function
Passing router to `fetch` callback instead of `websocket` option
fixSet `websocket: router` in Bun.serve options, not inside fetch
ZodError: Expected string, received number
Message payload does not match schema (e.g., `text` field is number instead of string)
fixEnsure client sends data matching the schema defined in the `message` handler
Error: Cannot find module 'zod'
Missing peer dependency `zod` (or `valibot`)
fixInstall zod: `bun add zod` or `npm install zod`
TypeScript errors on `ws.publish`/`ws.subscribe`: Property 'publish' does not exist on type 'WebSocket'
TypeScript not recognizing Bun's extended WebSocket types
fixInstall `@types/bun` and ensure tsconfig includes `"types": ["bun-types"]`
Audit
Dependencies
zodoptionalSchema validation for incoming messages
valibotoptionalAlternative schema validation library
@types/bunoptionalType definitions for Bun APIs