wexa-chat

library0.3.4jsnpmunverified

Chat core library built in TypeScript with MongoDB persistence and optional Redis pub/sub for cross-instance fanout. Current stable version 0.3.4. It provides a server-side API via initChat() and a lightweight browser client bundle (SocketProvider, useSocket, getSocketManager). Requires mongoose and ioredis as peer dependencies. Ships its own WebSocket transport using the ws library, with server-driven authentication via query parameters. Differentiators: server & client in one package, optional Redis for horizontal scaling, built-in text search, and a Next.js demo app pattern.

messaging

npm install wexa-chat

package ↗

INSTALL

IMPORT

SIG · WEXA-CHAT

wexa-chat

messagingjavascriptv0.3.4

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.

initChat

✓ import { initChat } from 'wexa-chat'

✗ const initChat = require('wexa-chat')

ESM export; CommonJS require will not work (package is ESM-only). Use dynamic import if needed.

SocketProvider

✓ import { SocketProvider } from 'wexa-chat/client'

✗ import { SocketProvider } from 'wexa-chat'

Client symbols are in a subpath export 'wexa-chat/client'. Importing from the top-level will fail.

useSocket

✓ import { useSocket } from 'wexa-chat/client'

✗ import { useSocket } from 'wexa-chat'

Same as SocketProvider; use the /client subpath.

getSocketManager

✓ import { getSocketManager } from 'wexa-chat/client'

✗ const getSocketManager = require('wexa-chat/client');

ESM-only. Also note that getSocketManager is a singleton getter, not a constructor.

ChatEvent

✓ import type { ChatEvent } from 'wexa-chat/client'

This is a TypeScript type, not a value. Use import type.

Initializes chat with MongoDB, no WebSocket server. Shows required peer mongoose and basic options.

import mongoose from 'mongoose'; import { initChat } from 'wexa-chat'; async function main() { await mongoose.connect(process.env.MONGODB_URI ?? ''); const chat = await initChat(mongoose, { participantModels: ['User'], memberRoles: ['member', 'admin'], mongoUri: process.env.MONGODB_URI ?? '', enableTextSearch: true, }); console.log('Chat initialized'); } main().catch(console.error);

Debug

Known issues

breakinginitChat() expected three arguments but the third (httpServer) is optional. If provided, it must be an HTTP server instance (not null or undefined) to attach WebSocket transport. Passing undefined when server not ready may cause runtime errors.

fix

Always pass httpServer only when it is available (e.g., after Next.js server is ready). Use the lazy initialization pattern shown in the README.

affects: >=0.1.0

gotchaClient bundle path must match server's socket.path. If you omit socket.path on server, it defaults to '/ws'. Client expects '/ws' by default; mismatch leads to 404.

fix

Ensure server socket.path (if set) equals client's expected path. Both default to '/ws'.

affects: >=0.1.0

gotchaRedis configuration is optional but if provided, both url OR (host and port) must be set. Missing fields cause runtime error.

fix

Use conditional: if (process.env.REDIS_URL) { redis: { url: process.env.REDIS_URL } } else if (process.env.REDIS_HOST) { ... }.

affects: >=0.1.0

deprecatedSocketConfig.cors option is currently accepted but not enforced. It may be removed in a future version.

fix

Do not rely on cors option; configure CORS at the HTTP server level instead.

affects: <=0.3.4

Errors

Common errors & fixes

Cannot find module 'wexa-chat/client' or its corresponding type declarations.

TypeScript cannot resolve subpath export. Ensure package.json exports includes './client'.

fix

Update tsconfig.json: set 'moduleResolution' to 'bundler' or 'node16'. Or use paths: { 'wexa-chat/client': ['./node_modules/wexa-chat/dist/client/index.d.ts'] }.

TypeError: initChat is not a function

CommonJS require() used instead of ESM import.

fix

Change to: import { initChat } from 'wexa-chat' (or dynamic import).

Error: listen EADDRINUSE :::3000

WebSocket server is trying to attach to a port already in use (e.g., Next.js dev server).

fix

Do not start a separate HTTP server; pass the existing Next.js HTTP server to initChat(). In Next.js, use the socket warm-up route.

Upgrade

Version history

0.3.4latest on npm

Audit

Dependencies

mongooserequiredRequired peer dependency for MongoDB models and connection

ioredisoptionalRequired peer dependency for Redis pub/sub (optional at runtime via config)

wsrequiredRequired peer dependency for WebSocket transport

reactrequiredRequired peer dependency for client bundle (SocketProvider, useSocket)

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

packagewexa-chat ↗