Registry / http-networking / nats.ws

nats.ws

JSON →
library1.30.3jsnpmunverified

nats.ws is a robust JavaScript and TypeScript client library designed for interacting with the NATS messaging system over WebSocket connections. It supports a variety of environments including modern web browsers, Deno, and Node.js (requiring a WebSocket shim for Node.js). The library is currently at version 1.30.3 and maintains a frequent release cadence, often aligning with updates to its underlying core client logic (NBC, which is derived from `nats.deno`). A key differentiating factor is its specialized focus on WebSocket connectivity and its tight integration with the NATS ecosystem. Users are advised that nats.ws is now considered an integrated component within the larger nats.js monorepo, and future development and major feature enhancements are primarily focused there. Comprehensive migration documentation is available for transitioning to nats.js.

npm install nats.ws
INSTALL
IMPORT
SIG · NATS.WS
N
nats.ws
http-networkingjavascriptv1.30.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

connect
✓ import { connect } from 'nats.ws';
✗ import { connect } from 'nats.ws/nats.js';
The direct 'nats.ws' import path is correct since v1.6.0 for ESM. Older versions (<1.6.0) used 'nats.ws/nats.js'. For CommonJS in Node.js, ensure a global WebSocket shim is provided before requiring.
StringCodec
✓ import { StringCodec } from 'nats.ws';
✗ import { StringCodec } from 'nats.ws/nats.js';
StringCodec is commonly used for encoding and decoding NATS messages, especially for string payloads. The import path changed with v1.6.0.
NatsConnection
✓ import type { NatsConnection } from 'nats.ws';
This is a TypeScript type import for the connection object returned by `connect()`.

Demonstrates connecting to a NATS server via WebSocket, subscribing to a subject, responding to requests, publishing messages, and gracefully closing the connection.

import { connect, StringCodec, Empty } from 'nats.ws'; // In a Node.js environment, you might need to shim WebSocket: // globalThis.WebSocket = require('websocket').w3cwebsocket; async function runNatsClient() { const servers = process.env.NATS_SERVER_URL ?? 'ws://localhost:9222'; console.log(`Connecting to NATS server at: ${servers}`); try { const nc = await connect({ servers: servers }); const sc = StringCodec.create(); console.log(`Connected to ${nc.getServer()}`); // Subscribe to a subject and respond to requests const sub = nc.subscribe('time.requests'); (async () => { for await (const m of sub) { const requestPayload = sc.decode(m.data); const response = `Current time for '${requestPayload}': ${new Date().toLocaleTimeString()}`; m.respond(sc.encode(response)); console.log(`[time.requests] received: '${requestPayload}' and responded with: '${response}'`); } console.log('Subscription to time.requests closed'); })(); // Publish a message and request a response const requestPayload = 'What time is it in Tokyo?'; const response = await nc.request('time.requests', sc.encode(requestPayload), { timeout: 1000 }); console.log(`[time.requests] received response: ${sc.decode(response.data)}`); // Publish a simple message nc.publish('hello', sc.encode('world')); console.log('Published "hello world" to subject "hello"'); await nc.flush(); // Ensure all messages are sent await nc.close(); console.log('Connection closed.'); } catch (err: any) { console.error(`Error connecting or interacting with NATS: ${err.message}`); if (err.code) { console.error(`NATS Error Code: ${err.code}`); } } } runNatsClient();
Debug
Known issues
breakingVersion 1.30.2 introduced a breaking change for NATS Object Store. Objects 512MB and larger might require a migration strategy. Users should consult the `nats.deno` v1.29.2 release notes (linked from `nats.ws` v1.30.2 changelog) for detailed migration steps before updating to avoid data integrity issues.
fix
Review the NATS.deno v1.29.2 release notes for specific instructions on migrating large object store data or adjusting your application logic.
affects: >=1.30.2
breakingVersion 1.30.3 includes updates to support a change in JetStream behavior in `nats-server` v2.10.26 and beyond. This may affect applications using JetStream features with older server versions, potentially leading to unexpected behavior.
fix
Ensure your `nats-server` is updated to version v2.10.26 or newer if utilizing JetStream features, or review the `nats.deno` v1.29.3 release notes for specific impacts and necessary client-side adjustments.
affects: >=1.30.3
deprecatedThe `nats.ws` project is now integrated into the `nats.js` monorepo. While `nats.ws` still receives maintenance updates, the primary development and new feature additions are concentrated in `nats.js`. Users are strongly encouraged to migrate to `nats.js` for new projects or existing ones to benefit from ongoing improvements and unified API.
fix
Migrate to the `nats.js` package. Refer to the `migration.md` document within the `nats.js` GitHub repository for detailed migration guidance.
affects: >=1.30.0
gotchaBy default, `nats.ws` assumes `wss://` (secure WebSocket) for server addresses provided as `host:port` (e.g., `localhost:9222`). If connecting to an insecure `ws://` endpoint, the protocol must be explicitly specified in the server URL (e.g., `ws://localhost:9222`).
fix
Always specify the full protocol in server URLs within `ConnectionOptions`, for example: `{ servers: ['ws://localhost:9222', 'wss://secure.nats.io'] }`.
affects: >=1.0.0
gotchaWhen connecting to NATS clusters with mixed `ws://` and `wss://` protocols, or if using a proxy that might advertise incorrect server updates, you may need to set the `ignoreServerUpdates` connection option to `true`. Failure to do so might cause the client to attempt to connect to an incompatible endpoint.
fix
For heterogeneous or proxied environments, configure your connection with `connect({ servers: [...], ignoreServerUpdates: true })` and explicitly list all valid server URLs.
affects: >=1.0.0
breakingThe primary import path for modules like `connect` changed with `v1.6.0`. Prior to `v1.6.0`, the correct ESM import was `import { connect } from 'nats.ws/nats.js';`. For `v1.6.0` and later, it is simply `import { connect } from 'nats.ws';`.
fix
Update your import statements to `import { connect } from 'nats.ws';` for versions 1.6.0 and higher. If targeting older versions, use the specific path.
affects: >=1.6.0
Errors
Common errors & fixes
ReferenceError: WebSocket is not defined
Running `nats.ws` in a Node.js environment without a global `WebSocket` implementation (shim). The library expects a W3C-compatible WebSocket API.
fix
Install a WebSocket library like `websocket` (`npm install websocket`) and shim it globally before importing `nats.ws`: `globalThis.WebSocket = require("websocket").w3cwebsocket;`.
NatsError: Protocol error -1 (code: 1006)
This error (or similar 'NatsError: Could not connect to server', 'EOF') indicates that the client failed to establish a proper WebSocket connection to the NATS server. Common causes include an incorrect server URL, the NATS server not running, a firewall blocking the connection, or unexpected data during the handshake.
fix
Verify the NATS server URL and port are correct (including `ws://` or `wss://` protocol). Ensure the NATS server is running and accessible from the client. Check for any network or firewall rules that might be blocking the connection.
Module not found: Can't resolve 'nats.ws/nats.js'
This error typically occurs in bundlers (e.g., Webpack, Rollup, Angular CLI) when `nats.ws` v1.6.0 or newer is used, but the import statement `import { connect } from 'nats.ws/nats.js';` (which was for older versions) is still present. Bundlers might also struggle with ESM/CJS resolution.
fix
For `nats.ws` v1.6.0 and newer, change the import statement to `import { connect } from 'nats.ws';`. If the issue persists with bundlers, ensure your bundler is correctly configured to handle ESM exports and resolve the main entry point (e.g., by ensuring `module` field in `package.json` is respected).
Upgrade
Version history
1.30.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
nats.ws — npm install nats.ws · libregistry