Registry / messaging / web3-providers-ws

web3-providers-ws

library4.0.8jsnpmunverified

WebSocket provider for web3.js 4.x (currently 4.0.8). Part of the web3.js v4 ecosystem, which migrated to ESM-only modules with native TypeScript support. Replaces the HTTP provider for real-time subscriptions (e.g., newBlockHeaders, logs). Key differentiators: supports reconnection with exponential backoff, custom headers, and authentication. Incompatible with web3.js v1.x provider APIs. Published under @ethereum-navigator scope; requires manual subscription management.

messaging

npm install web3-providers-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEB3-PROVIDERS-WS

web3-providers-ws

messagingjavascriptv4.0.8

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.

WebSocketProvider

✓ import { WebSocketProvider } from 'web3-providers-ws'

✗ const WebSocketProvider = require('web3-providers-ws')

ESM-only module; web3.js v4 uses named export. CJS require will fail unless using dynamic import or build tool with CJS interop.

WebSocketProviderOptions

✓ import type { WebSocketProviderOptions } from 'web3-providers-ws'

✗ import { WebSocketProviderOptions } from 'web3-providers-ws'

TypeScript users: the type is not a runtime value; use import type for correct tree-shaking. Available since v4.0.0.

default

✓ import WebSocketProvider from 'web3-providers-ws'

✗ import { default as WebSocketProvider } from 'web3-providers-ws'

This module does not have a default export. Only use named import { WebSocketProvider }.

Creates a WebSocket provider with reconnection options and starts a subscription to new block headers.

import { WebSocketProvider } from 'web3-providers-ws'; const provider = new WebSocketProvider( `wss://mainnet.infura.io/ws/v3/${process.env.INFURA_API_KEY ?? ''}`, { timeout: 30000, clientConfig: { maxReceivedFrameSize: 100000000, maxReceivedMessageSize: 100000000, }, reconnect: { auto: true, delay: 5000, maxAttempts: 5, onTimeout: true, }, } ); provider.on('connect', () => console.log('Connected')); provider.on('error', (err) => console.error('Error', err)); // Subscription example const sub = provider.request({ method: 'eth_subscribe', params: ['newHeads'], }); sub.on('data', (blockHeader) => console.log(blockHeader));

Debug

Known issues

breakingweb3-providers-ws v4.0.0 is ESM-only; importing via CommonJS require() will throw an error.

fix

Use dynamic import: const { WebSocketProvider } = await import('web3-providers-ws') or migrate project to ESM.

affects: >=4.0.0

breakingThe provider constructor no longer accepts the same options as web3 v1 (e.g., 'websocket' as a string for url). Options object structure changed.

fix

See the new options type: WebSocketProviderOptions. Pass url as first argument, options object as second.

affects: >=4.0.0

deprecatedSupport for custom headers via 'headers' option is deprecated as of v4.0.6; use 'clientConfig.headers' instead.

fix

Use clientConfig.headers: { Authorization: 'Bearer ...' } inside the options object.

affects: >=4.0.6 <4.0.9

gotchaThe WebSocketProvider does not auto-connect on instantiation; you must call provider.connect() or use web3.setProvider().

fix

See quickstart: call provider.connect() or use with web3 instance.

affects: >=4.0.0

gotchaSubscription event data emitted from the provider's request() method returns raw JSON-RPC response objects; not the same as web3.eth.subscribe event payloads.

fix

Use web3.eth.subscribe('newBlockHeaders') for parsed events.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: WebSocketProvider is not a constructor

Importing incorrectly (e.g., default import) when module has no default export.

fix

Use named import: import { WebSocketProvider } from 'web3-providers-ws'

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Using CommonJS require() on an ESM-only module.

fix

Use dynamic import: const { WebSocketProvider } = await import('web3-providers-ws') or set type: 'module' in package.json.

Error: connect ECONNREFUSED <host>:<port>

WebSocket server is not reachable or wrong endpoint URL.

fix

Verify the websocket URL (wss://) and ensure the server is running and accessible.

Upgrade

Version history

4.0.8latest on npm

Audit

Dependencies

web3-utilsrequiredUtility functions for Web3 core (sha3, toHex, etc.) used internally

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ChainSafe/web3.js ↗

packageweb3-providers-ws ↗

homepagehttps://github.com/ChainSafe/web3.js#readme ↗