Registry / messaging / nostr-websocket-utils

nostr-websocket-utils

library0.4.1jsnpmunverified

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.

messaging

npm install nostr-websocket-utils

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NOSTR-WEBSOCKET-UT

nostr-websocket-utils

messagingjavascriptv0.4.1

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.

NostrWSClient

✓ import { NostrWSClient } from 'nostr-websocket-utils'

✗ const NostrWSClient = require('nostr-websocket-utils'); const client = new NostrWSClient.Client(...)

Default export is not available; use named import. In CommonJS, use require but destructure.

createNostrServer

✓ import { createNostrServer } from 'nostr-websocket-utils'

✗ import createNostrServer from 'nostr-websocket-utils'

Named export, not default.

NostrWSError

✓ import { NostrWSError } from 'nostr-websocket-utils'

✗ import { NostrWSError } from 'nostr-websocket-utils/errors'

Error class is exported from the main entry point, not a subpath.

ConnectionOptions

✓ import type { ConnectionOptions } from 'nostr-websocket-utils'

✗ import { ConnectionOptions } from 'nostr-websocket-utils'

Use type import for TypeScript interfaces to avoid runtime overhead.

Shows how to create a Nostr WebSocket client and server with the library, including connection options and message handlers.

import { NostrWSClient, createNostrServer } from 'nostr-websocket-utils'; // Create client const client = new NostrWSClient('wss://relay.example.com', { logger: console, heartbeatInterval: 30000, handlers: { message: async (msg) => console.log('Received:', msg), error: (err) => console.error('Error:', err), close: () => console.log('Connection closed') } }); await client.connect(); // Create server const server = await createNostrServer(8080, { logger: console, heartbeatInterval: 30000, handlers: { message: async (ws, msg) => { console.log('Received message:', msg); } } }); // The library supports both ESM (import) and CommonJS (require). // For TypeScript, types are included. Ensure Node.js 18+ for ESM support.

Debug

Known issues

breakingConnectionOptions.handlers.message handler now expects async function in v0.4.0

fix

Update your message handler to be async: handlers: { message: async (msg) => { ... } }

affects: >=0.4.0

deprecatedThe `onMessage` option is deprecated; use `handlers.message` instead.

fix

Replace onMessage with handlers.message in the options object.

affects: >=0.4.0

gotchaESM import requires Node.js 18+ or a bundler like webpack/Vite.

fix

Use CommonJS require() in Node.js <18: const { NostrWSClient } = require('nostr-websocket-utils');

affects: >=0.4.0

gotchaLogger must implement specific interface (info, warn, error, debug); passing console is suggested but custom loggers must match.

fix

If using a custom logger, ensure it has info, warn, error, debug methods.

affects: >=0.3.0

breakingDefault export changed to named exports in v0.4.0

fix

Change import { NostrWSClient } from 'nostr-websocket-utils' (instead of import NostrWSClient from ...)

affects: >=0.4.0

Errors

Common errors & fixes

ERR_PACKAGE_PATH_NOT_EXPORTED: Package subpath './errors' is not defined

Importing from a subpath that does not exist in the package exports

fix

Import NostrWSError from 'nostr-websocket-utils' directly instead of 'nostr-websocket-utils/errors'

TypeError: client.connect is not a function

Using CommonJS require incorrectly, getting a module instead of the class

fix

Use const { NostrWSClient } = require('nostr-websocket-utils'); then new NostrWSClient(...)

Error: Module not found: Default condition should be last one

Using an older bundler that doesn't support the exports field correctly

fix

Upgrade bundler or use CommonJS (require) instead of ESM import

Invalid message format: expected array but got object

Sending a message that is not in the expected Nostr protocol format

fix

Ensure messages are arrays (e.g., ['EVENT', event]) or use the type-safe send methods

Upgrade

Version history

0.4.1latest on npm

Audit

Dependencies

pinooptionalLogging framework used for comprehensive logging; version 8.x required

nostr-crypto-utilsrequiredNostr cryptographic utilities for event signing and verification; required for full protocol support

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/HumanjavaEnterprises/nostr-websocket-utils ↗

packagenostr-websocket-utils ↗

homepagehttps://github.com/HumanjavaEnterprises/nostr-websocket-utils#readme ↗