{"id":48802,"library":"nostr-websocket-utils","title":"nostr-websocket-utils","description":"A TypeScript library for building Nostr protocol WebSocket clients and servers, providing robust connection management with automatic reconnection, heartbeat monitoring, message queueing, and comprehensive error handling. Version 0.4.1 is the current stable release, actively maintained with a monthly release cadence. Key differentiators include dual ESM/CommonJS module support, full Nostr NIP implementation (NIP-01, 02, 11, 15, 16, 20, 42), type-safe handlers, and integration with nostr-crypto-utils. Supports both browser and Node.js environments with secure WebSocket (WSS) connections and Vitest test suite.","status":"active","version":"0.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/HumanjavaEnterprises/nostr-websocket-utils","tags":["javascript","nostr","websocket","typescript","esm","commonjs","dual-module","nostr-protocol","websocket-client"],"install":[{"cmd":"npm install nostr-websocket-utils","lang":"bash","label":"npm"},{"cmd":"yarn add nostr-websocket-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add nostr-websocket-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Logging framework used for comprehensive logging; version 8.x required","package":"pino","optional":true},{"reason":"Nostr cryptographic utilities for event signing and verification; required for full protocol support","package":"nostr-crypto-utils","optional":false}],"imports":[{"note":"Default export is not available; use named import. In CommonJS, use require but destructure.","wrong":"const NostrWSClient = require('nostr-websocket-utils'); const client = new NostrWSClient.Client(...)","symbol":"NostrWSClient","correct":"import { NostrWSClient } from 'nostr-websocket-utils'"},{"note":"Named export, not default.","wrong":"import createNostrServer from 'nostr-websocket-utils'","symbol":"createNostrServer","correct":"import { createNostrServer } from 'nostr-websocket-utils'"},{"note":"Error class is exported from the main entry point, not a subpath.","wrong":"import { NostrWSError } from 'nostr-websocket-utils/errors'","symbol":"NostrWSError","correct":"import { NostrWSError } from 'nostr-websocket-utils'"},{"note":"Use type import for TypeScript interfaces to avoid runtime overhead.","wrong":"import { ConnectionOptions } from 'nostr-websocket-utils'","symbol":"ConnectionOptions","correct":"import type { ConnectionOptions } from 'nostr-websocket-utils'"}],"quickstart":{"code":"import { NostrWSClient, createNostrServer } from 'nostr-websocket-utils';\n\n// Create client\nconst client = new NostrWSClient('wss://relay.example.com', {\n  logger: console,\n  heartbeatInterval: 30000,\n  handlers: {\n    message: async (msg) => console.log('Received:', msg),\n    error: (err) => console.error('Error:', err),\n    close: () => console.log('Connection closed')\n  }\n});\n\nawait client.connect();\n\n// Create server\nconst server = await createNostrServer(8080, {\n  logger: console,\n  heartbeatInterval: 30000,\n  handlers: {\n    message: async (ws, msg) => {\n      console.log('Received message:', msg);\n    }\n  }\n});\n\n// The library supports both ESM (import) and CommonJS (require).\n// For TypeScript, types are included. Ensure Node.js 18+ for ESM support.","lang":"typescript","description":"Shows how to create a Nostr WebSocket client and server with the library, including connection options and message handlers."},"warnings":[{"fix":"Update your message handler to be async: handlers: { message: async (msg) => { ... } }","message":"ConnectionOptions.handlers.message handler now expects async function in v0.4.0","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Replace onMessage with handlers.message in the options object.","message":"The `onMessage` option is deprecated; use `handlers.message` instead.","severity":"deprecated","affected_versions":">=0.4.0"},{"fix":"Use CommonJS require() in Node.js <18: const { NostrWSClient } = require('nostr-websocket-utils');","message":"ESM import requires Node.js 18+ or a bundler like webpack/Vite.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"If using a custom logger, ensure it has info, warn, error, debug methods.","message":"Logger must implement specific interface (info, warn, error, debug); passing console is suggested but custom loggers must match.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Change import { NostrWSClient } from 'nostr-websocket-utils' (instead of import NostrWSClient from ...)","message":"Default export changed to named exports in v0.4.0","severity":"breaking","affected_versions":">=0.4.0"}],"env_vars":null,"search_vec":"'-01':57 '0.4.1':32 '02':58 '11':59 '15':60 '16':61 '20':62 '42':63 'activ':38 'automat':21 'browser':77 'build':9 'cadenc':44 'client':13,104 'commonj':95 'comprehens':28 'connect':18,85 'crypto':73 'current':35 'differenti':46 'dual':48,97 'dual-modul':96 'environ':80 'error':29 'esm':94 'esm/commonjs':49 'full':52 'handl':30 'handler':67 'heartbeat':23 'implement':55 'includ':47 'integr':69 'javascript':90 'key':45 'librari':7 'maintain':39 'manag':19 'messag':25 'modul':50,98 'monitor':24 'month':42 'nip':54,56 'node.js':79 'nostr':2,10,53,72,91,100 'nostr-crypto-util':71 'nostr-protocol':99 'nostr-websocket-util':1 'protocol':11,101 'provid':16 'queue':26 'reconnect':22 'releas':37,43 'robust':17 'safe':66 'secur':82 'server':15 'stabl':36 'suit':89 'support':51,75 'test':88 'type':65 'type-saf':64 'typescript':6,93 'util':4,74 'version':31 'vitest':87 'websocket':3,12,83,92,103 'websocket-cli':102 'wss':84","created_at":"2026-06-07T16:58:32.556536+00:00","updated_at":"2026-06-07T16:58:32.556536+00:00","problems":[{"fix":"Import NostrWSError from 'nostr-websocket-utils' directly instead of 'nostr-websocket-utils/errors'","cause":"Importing from a subpath that does not exist in the package exports","error":"ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './errors' is not defined"},{"fix":"Use const { NostrWSClient } = require('nostr-websocket-utils'); then new NostrWSClient(...)","cause":"Using CommonJS require incorrectly, getting a module instead of the class","error":"TypeError: client.connect is not a function"},{"fix":"Upgrade bundler or use CommonJS (require) instead of ESM import","cause":"Using an older bundler that doesn't support the exports field correctly","error":"Error: Module not found: Default condition should be last one"},{"fix":"Ensure messages are arrays (e.g., ['EVENT', event]) or use the type-safe send methods","cause":"Sending a message that is not in the expected Nostr protocol format","error":"Invalid message format: expected array but got object"}],"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/HumanjavaEnterprises/nostr-websocket-utils#readme","github":"https://github.com/HumanjavaEnterprises/nostr-websocket-utils","docs":null,"changelog":null,"pypi":null,"npm":"nostr-websocket-utils","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}}