Registry / http-networking / sockjs-client

sockjs-client

library1.6.1jsnpmunverified

SockJS-client is a browser JavaScript library (current stable version 1.6.1) that provides a WebSocket-like object, abstracting away underlying transport mechanisms. It aims to offer a coherent, cross-browser, full-duplex communication channel between the browser and a web server, even in environments without native WebSocket support or behind restrictive corporate proxies. The library first attempts to use native WebSockets, falling back to various browser-specific transports (like streaming or polling) if necessary. Releases are somewhat irregular but active, with recent updates focusing on security fixes and dependency updates. A key differentiator is its robust fallback mechanism, adhering closely to the HTML5 WebSocket API, and supporting cross-domain connections without requiring Flash. It explicitly requires a server counterpart, such as `sockjs-node`, for functionality.

http-networking web-framework

npm install sockjs-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SOCKJS-CLIENT

sockjs-client

http-networkingjavascriptv1.6.1

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.

SockJS

✓ import SockJS from 'sockjs-client';

✗ const SockJS = require('sockjs-client');

ESM import is recommended for modern JavaScript environments and module bundlers.

SockJS (browser global)

✓ <script src="https://cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js"></script> // SockJS is then available as a global variable

When included directly via a script tag in HTML, SockJS becomes a global object.

SockJS (TypeScript)

✓ import SockJS from 'sockjs-client'; // Or if type errors occur: import * as SockJS from 'sockjs-client';

✗ import { SockJS } from 'sockjs-client';

TypeScript users might need `import * as SockJS from 'sockjs-client';` or `declare module 'sockjs-client';` if declaration files are missing or incompatible, especially with older configurations. Installing `@types/sockjs-client` is also a common step if available.

Demonstrates how to establish a connection with a SockJS server, send messages, and handle connection lifecycle events like opening, receiving messages, and closing. It also highlights the necessity of a server counterpart.

import SockJS from 'sockjs-client'; // Ensure a SockJS server is running, e.g., on http://localhost:8080/my_websocket // For example, using sockjs-node: // const sockjs = require('sockjs'); // const http = require('http'); // const server = http.createServer(); // const echo = sockjs.createServer(); // echo.on('connection', (conn) => { // conn.on('data', (message) => { conn.write(message); }); // conn.on('close', () => { console.log('Client disconnected from server'); }); // }); // echo.installHandlers(server, { prefix: '/my_websocket' }); // server.listen(8080, '0.0.0.0', () => { console.log('SockJS server listening on 8080'); }); const socket = new SockJS('http://localhost:8080/my_websocket'); socket.onopen = () => { console.log('SockJS connection opened'); socket.send('Hello from client!'); }; socket.onmessage = (event) => { console.log('Received message:', event.data); // Optionally close the connection after receiving a message // socket.close(); }; socket.onclose = (event) => { console.log('SockJS connection closed:', event.code, event.reason); if (!event.wasClean) { console.error('Connection abruptly disconnected.'); // Implement re-connection logic here } }; socket.onerror = (error) => { console.error('SockJS error:', error); }; // Example: Send a message every 3 seconds // setInterval(() => { // if (socket.readyState === SockJS.OPEN) { // socket.send('Ping!'); // } // }, 3000);

Debug

Known issues

breakingSockJS-client v1.6.0 removed `agent: false` to allow usage of `globalAgent` in Node.js environments. This change could subtly alter HTTP agent behavior, potentially affecting proxy or connection pooling configurations for Node.js clients.

fix

Review Node.js client configurations, especially those relying on `agent: false` behavior or custom HTTP agents, to ensure compatibility with `globalAgent` usage. Explicitly define HTTP agents if specific behavior is required.

affects: >=1.6.0

breakingVersion 1.3.0 reverted the `debug` dependency from v4 (which used ES6) back to `^3`. Projects explicitly relying on `debug` v4 features or ES6 syntax from the `debug` library might experience issues if `sockjs-client` is a transitive dependency that forces an older `debug` version.

fix

Ensure your project's `debug` dependency aligns with `sockjs-client`'s requirement or use dependency overrides if possible. Check for `debug` related errors during build or runtime.

affects: >=1.3.0 <1.4.0

gotchaSockJS requires a dedicated server-side implementation (e.g., `sockjs-node` for Node.js, or similar for other languages). It is not a standalone WebSocket server but a client library for a specific protocol.

fix

Ensure a compatible SockJS server is correctly deployed and accessible at the specified URL. The client cannot connect to a standard WebSocket server without a SockJS server in between.

affects: >=0.0.1

gotchaWhen connecting from the browser via script tag, the `SockJS` object is globally available. However, in modern module-based environments (ESM/CommonJS), it must be explicitly imported, typically as a default export. Incorrect import statements are a common source of 'SockJS is not defined' errors.

fix

For ESM, use `import SockJS from 'sockjs-client';`. For CommonJS, use `const SockJS = require('sockjs-client');`. If using TypeScript, `import * as SockJS from 'sockjs-client';` or `declare module 'sockjs-client';` might be necessary.

affects: >=0.0.1

gotchaSockJS uses iframe-based transports for cross-origin communication in some older browsers. This can lead to issues with `webpack-dev-server` if there's a version mismatch of `sockjs-client` between the bundled client and the main application, resulting in 'Incompatible SockJS!' errors.

fix

Ensure that all `sockjs-client` versions in your project's dependency tree (including transitive dependencies from tools like `webpack-dev-server`) are consistent. Upgrading `webpack-dev-server` to its latest major version is often recommended to resolve such issues.

affects: >=1.5.0

gotchaSockJS has an in-browser limitation preventing more than one active SockJS connection to a single domain simultaneously, as each session uses two outgoing connections (one for sending, one for receiving). Attempting to open multiple connections can lead to unexpected behavior or connection failures.

fix

Design your application to utilize a single SockJS connection per domain, multiplexing messages over that single channel if necessary. Avoid creating multiple `new SockJS()` instances to the same server endpoint.

affects: >=0.0.1

Errors

Common errors & fixes

ReferenceError: SockJS is not defined

The SockJS client library was not correctly loaded or imported into the JavaScript environment. This often happens when mixing global script tag usage with module imports, or when the module bundler fails to resolve the import.

fix

If using a module system (ESM/CommonJS), ensure you have `import SockJS from 'sockjs-client';` (or `const SockJS = require('sockjs-client');`). If loading via a script tag, ensure the `<script>` tag is correctly placed and the path to `sockjs.min.js` is correct.

WebSocket connection to 'ws://localhost:8080/sockjs/info?t=...' failed: Error during WebSocket handshake: Unexpected response code: 500

The SockJS server endpoint is not correctly configured, not running, or is returning an error during the initial handshake. This often indicates a problem on the server side rather than the client.

fix

Verify that your SockJS server (e.g., `sockjs-node`) is running, accessible at the specified URL, and properly configured to handle SockJS connections. Check the server logs for specific error messages.

Uncaught SyntaxError: The requested module './../node_modules/sockjs-client/lib/entry.js' does not provide an export named 'default'

This error typically occurs in ESM environments when `sockjs-client` is treated as an ES module but it primarily provides a CommonJS export, or when a bundler struggles to correctly transpile or interpret its module format.

fix

For TypeScript, try `import * as SockJS from 'sockjs-client';`. For bundlers like Webpack or Rollup, ensure CommonJS plugins are correctly configured to handle `sockjs-client` (e.g., `@rollup/plugin-commonjs` for Rollup). You might also need to add `"type": "module"` to your `package.json` if using native ESM in Node.js, though `sockjs-client` might still require a CommonJS wrapper.

SecurityError: Blocked a frame with origin "http://localhost:3000" from accessing a cross-origin frame.

This usually indicates a browser security restriction related to cross-origin communication, often when SockJS falls back to iframe-based transports, or if there are misconfigured CORS headers on the server.

fix

Ensure your SockJS server explicitly sets appropriate CORS headers (`Access-Control-Allow-Origin`, etc.) for your client's origin. For iframe transports, connecting from the same parent domain as the main site can help.

Upgrade

Version history

1.6.1latest on npm

Audit

Dependencies

sockjs-noderequiredSockJS-client requires a compatible server-side implementation to establish connections and handle communication. `sockjs-node` is the official Node.js server counterpart.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sockjs/sockjs-client ↗

packagehttps://www.npmjs.com/package/sockjs-client ↗

homepagehttp://sockjs.org ↗