ic-websocket-js

library0.5.0jsnpmunverified

A JavaScript/TypeScript SDK for WebSocket communication on the Internet Computer (IC) blockchain. Version 0.5.0, actively developed. Enables real-time, bidirectional messaging between dapps and canisters via IC WebSocket gateways. Differentiates from standard WebSocket by integrating with IC authentication and agent-based calls. Requires @dfinity/agent, @dfinity/candid, @dfinity/identity-secp256k1, and @dfinity/principal as peer dependencies. Ships TypeScript types.

messaging

npm install ic-websocket-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IC-WEBSOCKET-JS

ic-websocket-js

messagingjavascriptv0.5.0

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.

IcWebSocket

✓ import { IcWebSocket } from 'ic-websocket-js'

✗ import icWebSocket from 'ic-websocket-js'

Default export is not available; use named import.

IcWebSocketEvent

✓ import { IcWebSocketEvent } from 'ic-websocket-js'

✗ import { IcWebSocketEvent } from 'ic-websocket-js'

Type import; also available as a type definition.

createCanisterWebSocket

✓ import { createCanisterWebSocket } from 'ic-websocket-js'

Utility function for creating WebSocket connections from canister context.

Creates an IC WebSocket connection using a generated identity and agent, listens for events, and sends a message.

import { IcWebSocket } from 'ic-websocket-js'; import { HttpAgent } from '@dfinity/agent'; import { Secp256k1KeyIdentity } from '@dfinity/identity-secp256k1'; import { Principal } from '@dfinity/principal'; const identity = Secp256k1KeyIdentity.generate(); const agent = await HttpAgent.create({ identity }); const canisterId = Principal.fromText('rrkah-fqaaa-aaaaa-aaaaa-c'); // example const ws = new IcWebSocket({ canisterId, agent, gatewayUrl: 'wss://gateway.example.com/ws' }); ws.addEventListener('open', () => { console.log('connected'); ws.send(JSON.stringify({ msg: 'hello' })); }); ws.addEventListener('message', (event) => { console.log('received:', event.data); }); ws.addEventListener('close', () => { console.log('disconnected'); }); ws.connect();

Debug

Known issues

gotcharequires peer dependencies to be installed separately

fix

Install @dfinity/agent, @dfinity/candid, @dfinity/identity-secp256k1, @dfinity/principal as peers.

affects: >=0.5.0

gotchagatewayUrl must be a WebSocket URL (wss://) pointing to an IC WebSocket Gateway

fix

Ensure gatewayUrl is correct and the gateway is running.

affects: >=0.5.0

breakingIcWebSocket constructor parameters changed in v0.5.0

fix

Use the new object-based configuration: { canisterId, agent, gatewayUrl }. Previous versions may have used positional arguments.

affects: >=0.5.0

deprecatedThe method connect() must be called explicitly after adding event listeners

fix

Add event listeners before calling connect() to avoid missing events.

affects: >=0.5.0

Errors

Common errors & fixes

Cannot find module '@dfinity/agent' or its corresponding type declarations.

Missing peer dependencies.

fix

npm install @dfinity/agent @dfinity/candid @dfinity/identity-secp256k1 @dfinity/principal

TypeError: Class constructor IcWebSocket cannot be invoked without 'new'

Using IcWebSocket as a function instead of a class constructor.

fix

Use 'new IcWebSocket(...)'

Uncaught (in promise) TypeError: ws.send is not a function

WebSocket connection not yet open; send() called before connect() or open event.

fix

Call send() only after the 'open' event fires.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

@dfinity/agentrequiredRequired for interacting with the Internet Computer agent and making authenticated calls.

@dfinity/candidrequiredRequired for Candid serialization/deserialization of messages.

@dfinity/identity-secp256k1requiredProvides identity and signing for WebSocket connections.

@dfinity/principalrequiredUsed for handling Principal identifiers.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/omnia-network/ic-websocket-sdk-js ↗

packageic-websocket-js ↗

homepagehttps://github.com/omnia-network/ic-websocket-sdk-js#readme ↗