Refined SockJS documentation: updated examples for clarity, aligned terminology, addressed Angular compatibility, and emphasized WebSocket-first approach with SockJS fallback.

Author: Deepak Kumar

_posts/2018-09-10-using-stomp-with-sockjs.md

@@ -14,42 +14,40 @@ redirect_from:
 **There are a large number of obsolete (and copied from one another)
 examples for these libraries that use SockJS.
 In reality, there is very little chance that you need SockJS.
-Unless you know, for sure, you do not need SockJS.**
+Unless you know for sure, you do not need SockJS.**
 
-This guide covers how to use [SockJS client] instead of WebSockets as underlying transport.
+This guide covers how to use [SockJS client] instead of WebSockets as the underlying transport.
 
 **For Spring STOMP users:**
-_There are few tutorials/guides that implicitly suggest that you need SockJS to use STOMP.
-That is incorrect, you only need SockJS if you need to support old browsers._
+_Some tutorials/guides implicitly suggest that you need SockJS to use STOMP.
+That is incorrect — you only need SockJS if you need to support ancient browsers._
 
 ## Do you need SockJS?
 
-As of 2018, WebSocket support in browsers is ubiquitous.
+WebSocket support in modern browsers is ubiquitous.
 Please check [https://caniuse.com/#feat=websockets](https://caniuse.com/#feat=websockets).
 Depending on your user base, you can skip this page.
 
 You can use [SockJS client] to support browsers that do not support WebSockets natively.
 
-You would need to consider the following:
+You should consider the following:
 
-- URL protocol conventions are different for WebSockets (`ws:`/`wss:`) and SockJS (`http:` or `https:`).
-- Internal handshake sequences are different — so, some brokers will use different end points for
-  both protocols.
-- Neither of these allows custom headers to be set during the HTTP handshake.
-- SockJS internally supports different transport mechanisms. You might face specific limitations
-  depending on actual transport in use.
-- Auto reconnect is not quite reliable with SockJS.
+- URL protocol conventions are different for WebSockets (`ws:`/`wss:`) and SockJS (`http:`/`https:`).
+- Handshake sequences differ — some brokers expose different endpoints for both protocols.
+- Neither protocol allows custom headers during the initial HTTP handshake.
+- SockJS uses multiple transport mechanisms; you may face limitations depending on the transport in use.
+- Auto-reconnect may be less reliable with SockJS.
 - Heartbeats may not be supported over SockJS by some brokers.
-- SockJS does not allow more than one simultaneous connection to the same broker.
-  This usually is not a problem for most of the applications.
+- SockJS typically does not allow more than one simultaneous connection to the same broker.
+  This is usually not a problem for most applications.
 
-It is advised to use WebSockets by default and then fall back to SockJS if the browser does not support.
+Prefer native WebSockets by default and fall back to SockJS only if the browser lacks WebSocket support or your deployment requires HTTP-only transport.
 
 ## Basic installation
 
 ### In Node.js environments
 
-Please install the latest[SockJS client]:
+Please install the latest [SockJS client]:
 
 ```bash
 $ npm install sockjs-client --save
@@ -60,7 +58,10 @@ $ npm install sockjs-client --save
 Depending on your programming language/environment, you may have to `import` or `require` it:
 
 ```typescript
-import * as SockJS from 'sockjs-client';
+// ESM
+import SockJS from 'sockjs-client';
+// or (older TypeScript configs)
+// import * as SockJS from 'sockjs-client';
 ```
 
 ### In the browser
@@ -73,15 +74,17 @@ Add the following to include directly in the browser:
 
 ## Implement a webSocketFactory
 
-Create a function that returns an object similar to WebSocket (typically SockJS instance).
+Create a function that returns an object similar to WebSocket (typically a SockJS instance).
 
 ```typescript
+import SockJS from 'sockjs-client';
+
 export function mySocketFactory() {
   return new SockJS('http://127.0.0.1:15674/stomp');
 }
 ```
 
-This function should return a WebSocket compatible object.
+This function should return a WebSocket-compatible object.
 
 **Note: this function may be invoked multiple times.
 Each time a broker (re)connects, it needs a new instance of WebSocket/SockJS.**
@@ -90,16 +93,19 @@ Each time a broker (re)connects, it needs a new instance of WebSocket/SockJS.**
 
 You should set [webSocketFactory] instead of [brokerURL] in your configuration.
 
-You can even check if WebSocket is available and accordingly use SockJS as a fallback.
+You can also detect WebSocket availability and use SockJS as a fallback.
 See the example below.
 
-**Note: if you set both [webSocketFactory] takes precedence.**
+**Note: if you set both, [webSocketFactory] takes precedence.**
 
 ## Example with stompjs
 
 ```javascript
-const client = new StompJs.Client({
-  brokerURL: 'ws://localhost:15674/ws',
+// ESM usage recommended
+import { Client } from '@stomp/stompjs';
+
+const client = new Client({
+  brokerURL: 'ws://localhost:15674/ws', // Native WebSocket URL (if available)
   connectHeaders: {
     login: 'user',
     passcode: 'password',
@@ -114,7 +120,7 @@ const client = new StompJs.Client({
 
 // Fallback code
 if (typeof WebSocket !== 'function') {
-  // For SockJS you need to set a factory that creates a new SockJS instance
+  // For SockJS, set a factory that creates a new SockJS instance
   // to be used for each (re)connect
   client.webSocketFactory = function () {
     // Note that the URL is different from the WebSocket URL
@@ -123,15 +129,15 @@ if (typeof WebSocket !== 'function') {
 }
 
 client.onConnect = function (frame) {
-  // Do something, all subscribes must be done is this callback
-  // This is needed because this will be executed after a (re)connect
-};
+  // Do something; all subscribes must be done in this callback
+  // This is needed because it executes after a (re)connect
+  };
 
 client.onStompError = function (frame) {
-  // Will be invoked in case of error encountered at Broker
-  // Bad login/passcode typically will cause an error
-  // Complaint brokers will set `message` header with a brief message. Body may contain details.
-  // Compliant brokers will terminate the connection after any error
+  // Invoked in case of an error reported by the broker
+  // Bad login/passcode typically causes an error
+  // Compliant brokers set the `message` header with a brief message; the body may contain details.
+  // Compliant brokers terminate the connection after any error
   console.log('Broker reported error: ' + frame.headers['message']);
   console.log('Additional details: ' + frame.body);
 };
@@ -140,14 +146,31 @@ client.activate();
 ```
 
 Compare the above against the sample in [using StompJS]({% link _posts/2018-06-29-using-stompjs-v5.md %}),
-only addition is the fallback code trying to use SockJS if WebSocket is unavailable.
-You will need to include latest [SockJS client] in your web page.
+the only addition is the fallback code to use SockJS if WebSocket is unavailable.
+You will need to include the latest [SockJS client] in your web page when using the UMD build.
+
+### Always using SockJS (when your server exposes only HTTP endpoints)
+
+If your server provides only the SockJS endpoint (no native WebSocket), configure the factory unconditionally:
+
+```javascript
+import { Client } from '@stomp/stompjs';
+import SockJS from 'sockjs-client';
+
+const client = new Client({
+  webSocketFactory: () => new SockJS('https://example.com/stomp'),
+  connectHeaders: { login: 'user', passcode: 'password' },
+  reconnectDelay: 5000,
+});
+
+client.activate();
+```
 
-## SockJS in Angular6
+## SockJS in Angular (Angular 6+)
 
 See: [ng2-stompjs/issues/70].
 
-When you are using SockJS in an Angular6 project you might get **"global is not defined"**.
+When you are using SockJS in an Angular project you might get **"global is not defined"**.
 
 The underlying issue can only be fixed by SockJS or Angular teams.
 Try any of the following workarounds (from [ng2-stompjs/issues/70]):
@@ -160,7 +183,7 @@ Try any of the following workarounds (from [ng2-stompjs/issues/70]):
 </script>
 ```
 
-- Add following to your `polyfill.ts`:
+- Add the following to your `polyfills.ts`:
 
 ```typescript
 (window as any).global = window;