Refined FAQ documentation: improved clarity, updated links, aligned terminology, consolidated examples, and emphasized modern usage patterns across multiple topics.

Deepak Kumar · Deepak Kumar · commit 6594d6050ff6 · 2025-09-17T19:50:41.000-04:00
diff --git a/_faqs/alternatives-are-there-any-missing-features-from-original-jeff-mesnil-stompjs.md b/_faqs/alternatives-are-there-any-missing-features-from-original-jeff-mesnil-stompjs.md
@@ -4,11 +4,11 @@ group: Jeff Mesnil's stompjs
 priority: ZAE
 ---
 
-Jeff Mesnil's stompjs supports STOMP over TCP when used in the NodeJS environment.
-Other than this, there is no known missing functionality.
-If you intend to use this feature, please raise an issue.
+The original `stompjs` offered STOMP over TCP in Node.js.
+`@stomp/stompjs` focuses on STOMP over WebSocket (WebStomp), which is supported by most brokers.
 
-Jeff Mesnil's stompjs is not fully compliant to STOMP protocol.
-The `@stomp/stompjs` strictly adheres the protocol.
-This might, in some cases, give behavioral differences.
-If you are facing any such issues, please raise an issue.
+`@stomp/stompjs` adheres more strictly to the STOMP specification than the original library,
+so behavior may differ in edge cases. If you hit issues, please raise an issue.
+
+If you specifically need STOMP over TCP in Node.js, consider using the TCP Wrapper:
+https://github.com/stomp-js/tcp-wrapper
diff --git a/_faqs/alternatives-how-do-i-migrate-from-jeff-mesnil-s-stompjs.md b/_faqs/alternatives-how-do-i-migrate-from-jeff-mesnil-s-stompjs.md
@@ -4,12 +4,7 @@ group: Jeff Mesnil's stompjs
 priority: ZAC
 ---
 
-Please see [upgrading stompjs](/guide/stompjs/upgrading-stompjs.html)
-guide.
+See the upgrade guide: {% link _posts/2018-09-08-upgrading-stompjs.md %}
 
-The v4 of this library is backwards compatible with the original stompjs.
-In all likelihoods your working code would work under compatibility mode of
-v5.
-
-To use newer features like automatic reconnection, compliance with STOMP
-standards, and binary payloads, you would need to upgrade to newer syntax.
+v4 provides compatibility with the original `stompjs`.
+For newer features (auto-reconnect, full STOMP compliance, binary payloads), migrate to the v5+ API.
diff --git a/_faqs/alternatives-how-is-it-related-to-stompjs-from-jeff-mesnil.md b/_faqs/alternatives-how-is-it-related-to-stompjs-from-jeff-mesnil.md
@@ -5,14 +5,9 @@ priority: ZAA
 ---
 
 [stompjs](https://www.npmjs.com/package/stompjs)
-from [Jeff Mesnil](http://jmesnil.net/) has been one of the initial
-STOMP implementations for JavaScript.
-However, the original author has no longer been maintaining it since 2016.
-`@stomp/stompjs` started as a maintained fork.
+from [Jeff Mesnil](http://jmesnil.net/) was one of the first STOMP implementations for JavaScript.
+It has not been maintained since 2016. `@stomp/stompjs` started as a maintained fork.
 
-`@stomp/stompjs` v4 is an enhanced version of
-[stompjs](https://www.npmjs.com/package/stompjs)
-from [Jeff Mesnil](http://jmesnil.net/).
-
-Version 5 of `@stomp/stompjs` has been bottom up rewritten in TypeScript.
-This version supports the older API in compatibility mode.
+`@stomp/stompjs` v4 enhanced the original API and remained compatible.
+From v5 onward, `@stomp/stompjs` was rewritten in TypeScript and offers a modern API while
+retaining a compatibility mode.
diff --git a/_faqs/authentication-can-i-use-token-based-authentication-with-these-libraries.md b/_faqs/authentication-can-i-use-token-based-authentication-with-these-libraries.md
@@ -4,25 +4,13 @@ group: Authentication
 priority: GAA
 ---
 
-Even though [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
-is somewhat similar to HTTP(S), it differs in one very important aspect — it
-does not allow control of headers.
+While WebSocket is initiated via HTTP(S), custom headers cannot be set during the handshake.
 
-This poses a limitation on using token-based authentication schemes using HTTP headers.
-
-Conventional brokers do not expect any authentication information as part of
-HTTP headers or HTTP connection parameters.
-These instead rely on STOMP protocol's
-[CONNECT Frame](https://stomp.github.io/stomp-specification-1.2.html#CONNECT_or_STOMP_Frame).
-This frame can have headers as key/value pairs.
-You can control these by setting
-[connectHeaders](https://stomp-js.github.io/api-docs/latest/classes/Client.html#connectHeaders)
-configuration option.
-You can pass any pair of strings as keys and values.
-
-So, typically, for token-based authentication you will pass the token as part of
+STOMP brokers typically expect authentication in the STOMP
+[CONNECT frame](https://stomp.github.io/stomp-specification-1.2.html#CONNECT_or_STOMP_Frame)
+via headers. You can supply arbitrary key/value pairs using
 [connectHeaders](https://stomp-js.github.io/api-docs/latest/classes/Client.html#connectHeaders).
-Check your broker documentation for details.
 
-If you are using Spring, please check
-[https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#websocket-stomp-authentication-token-based](https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#websocket-stomp-authentication-token-based)
+For token-based authentication, include your token in `connectHeaders` as required by your broker.
+If using Spring, see:
+https://docs.spring.io/spring-framework/reference/web/websocket/stomp/authentication.html#websocket-stomp-authentication-token-based
diff --git a/_faqs/authentication-my-authentication-tokens-expire-where-should-i-write-code-to-acquire-fresh-tokens.md b/_faqs/authentication-my-authentication-tokens-expire-where-should-i-write-code-to-acquire-fresh-tokens.md
@@ -4,12 +4,9 @@ group: Authentication
 priority: GAC
 ---
 
-The suggested place to acquire fresh tokens is
-[beforeConnect](https://stomp-js.github.io/api-docs/latest/classes/Client.html#beforeConnect)
-callback.
-You can update the
+Use the [beforeConnect](https://stomp-js.github.io/api-docs/latest/classes/Client.html#beforeConnect)
+callback to fetch a fresh token and update
 [connectHeaders](https://stomp-js.github.io/api-docs/latest/classes/Client.html#connectHeaders)
-after you have acquired a fresh token.
+just before each (re)connect.
 
-If you need to fetch a token using an async request (say using an XHR),
-you can set an async function as the callback.
+If you need async fetching (e.g., HTTP call), make `beforeConnect` an async function.
diff --git a/_faqs/general-bundlers.md b/_faqs/general-bundlers.md
@@ -6,6 +6,5 @@ priority: ADK
 
 Yes.
 
-These libraries include ES6 modules in the distribution,
-so, any environment that uses `import` will be able to find modules
-without any additional configuration.
+The packages ship ES modules compatible with modern bundlers (e.g., Vite, Rollup, Webpack, Parcel).
+Tree-shaking works well when you import the specific symbols you need.
diff --git a/_faqs/general-can-these-libraries-be-used-with-es6-or-typescript.md b/_faqs/general-can-these-libraries-be-used-with-es6-or-typescript.md
@@ -6,10 +6,8 @@ priority: ACC
 
 Yes.
 
-From 2023, these libraries are distributed as Javascript modules as default.
-These can be used with `import`.
+These libraries are distributed as JavaScript ES Modules by default and can be imported with `import`.
 
-All these libraries have been developed in TypeScript and type definition
-files are included in releases.
+All libraries are developed in TypeScript and include type definitions.
 
-In addition, a UMD bundle is included to be used as a html script tag.
+A UMD bundle is also provided for direct use via a `<script>` tag in browsers.
diff --git a/_faqs/general-how-do-i-enable-logging.md b/_faqs/general-how-do-i-enable-logging.md
@@ -4,8 +4,7 @@ group: General
 priority: AGA
 ---
 
-Please see [enabling debug log](/guide/stompjs/using-stompjs-v5.html#debug).
+See the Debug section in the guide: {% link _posts/2018-06-29-using-stompjs-v5.md %}#debug
 
-The console debug output may have NULL characters, which will prevent it from copying and pasting
-into a GitHub issue.
-In such cases, save it as a text file and attach with the issue.
+The console debug output may contain NULL characters, which can break copy/paste into an issue.
+If that happens, save the output to a text file and attach it to the issue.
diff --git a/_faqs/general-i-am-using-angular-which-of-stompjs-rx-stomp-or-ng2-stompjs-should-i-use.md b/_faqs/general-i-am-using-angular-which-of-stompjs-rx-stomp-or-ng2-stompjs-should-i-use.md
@@ -10,3 +10,18 @@ There is a tutorial for using `rx-stomp` with Angular. Please see [guides](/#get
 
 Having said all of these, you can use any of the variants.
 Developers have reported successfully using `stompjs` directly with Angular.
+
+Angular makes heavy use of [RxJS](https://github.com/ReactiveX/RxJS), so `rx-stomp` is the recommended choice for Angular apps.
+
+Why `rx-stomp`:
+- Native RxJS APIs (Observables) for messages, connection state, and lifecycles.
+- Subscriptions auto-reestablish on reconnects without manual bookkeeping.
+- Works well with Angular patterns (services, dependency injection, async pipes).
+
+When to use `stompjs`:
+- You want the lightest possible dependency set and prefer imperative APIs.
+- You are not using RxJS in your app.
+
+Helpful links:
+- Angular sample using `@stomp/rx-stomp`: https://github.com/stomp-js/rx-stomp-angular
+- Migrating from `ng2-stompjs` to `rx-stomp`: {% link _posts/2022-03-03-ng2-stompjs-to-rx-stomp.md %}
diff --git a/_faqs/general-polyfills-classes.md b/_faqs/general-polyfills-classes.md
@@ -4,4 +4,8 @@ group: General
 priority: AKA
 ---
 
-Please see [StompJs v5: Polyfills](/guide/stompjs/rx-stomp/polyfills-for-stompjs.html)
+Please see the Polyfills guide: {% link _posts/2018-06-28-polyfills-for-stompjs.md %}
+
+- Node.js: provide a WebSocket implementation and ensure TextEncoder/TextDecoder exist.
+- React Native: add TextEncoder/TextDecoder; WebSocket is provided by RN.
+- Browsers: typically no polyfills are required.
diff --git a/_faqs/general-tree-shaking.md b/_faqs/general-tree-shaking.md
@@ -4,6 +4,28 @@ group: General
 priority: ADM
 ---
 
-Yes.
+Yes — when you consume them as ES modules.
 
-Please update the latest versions before reporting any issues related to tree shaking.
+Tips for best results:
+- Use ESM and named imports:
+  ```javascript
+  import { Client } from '@stomp/stompjs';
+  // good: only Client is bundled
+  ```
+  Avoid wildcard or UMD usage in apps you intend to tree-shake:
+  ```javascript
+  // avoid for app bundles (prevents effective tree-shaking)
+  // import * as StompJs from '@stomp/stompjs';
+  // <script src=".../stomp.umd.js"></script>
+  ```
+- Import only what you use; don’t re-export the entire package from your own index.
+- Build in production mode so your bundler can perform dead-code elimination.
+  - Webpack: `mode: 'production'` (enables `optimization.usedExports`)
+  - Rollup/Vite/Parcel: production builds enable tree-shaking by default
+- Keep “side-effect free” usage:
+  - Prefer top-level imports of symbols you actually use over side-effect-only imports.
+- Verify with a bundle analyzer (e.g., `webpack-bundle-analyzer`, `rollup-plugin-visualizer`).
+
+Note:
+- The UMD bundle is intended for direct `<script>` use in browsers and is not tree‑shakeable.
+- If you still see unexpected code retained, ensure all dependencies and your bundler are up to date and that you’re not pulling the UMD build accidentally.
diff --git a/_faqs/general-what-are-heartbeats-should-i-bother.md b/_faqs/general-what-are-heartbeats-should-i-bother.md
@@ -1,23 +1,18 @@
 ---
-question: 'What are Heartbeats? Should I bother?'
+question: 'What are heartbeats? Should I bother?'
 group: General
 priority: AEA
 ---
 
-Most STOMP 1.1+ brokers will support heart beats.
-These can be from the broker to the client (incoming)
-or the client to the broker (outgoing).
-When enabled, periodic heartbeats are sent.
-If heartbeats are not received within specified time (along with some grace time),
-the connection is assumed to be stale and will be terminated.
+Most STOMP 1.1+ brokers support heartbeats — periodic pings either
+from the broker to the client (incoming) or the client to the broker (outgoing).
+If heartbeats are not received within a configured time (plus grace), the connection is considered stale and closed.
 
-SockJS may not support heart beats.
-See [using STOMP with SockJS](/guide/stompjs/rx-stomp/using-stomp-with-sockjs.html).
+SockJS may not support heartbeats with some brokers.
+See {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}.
 
-Whether you should use heart beats is a complex decision.
-If you use it, a stale connection will be detected sooner.
-However, it also means packets (actually a one-byte payload) will keep getting sent/received even when
-there is no application traffic.
+Whether you should enable heartbeats depends on your needs:
+- Pro: stale connections are detected sooner.
+- Con: small packets continue even when there is no app traffic.
 
-Please see the [Heart Beats](/guide/stompjs/using-stompjs-v5.html#heart-beating)
-topic for usage details.
+See the Heart-beating section for usage details: {% link _posts/2018-06-29-using-stompjs-v5.md %}#heart-beating
diff --git a/_faqs/general-what-documentation-is-available.md b/_faqs/general-what-documentation-is-available.md
@@ -5,6 +5,6 @@ priority: AAC
 ---
 
 - Comprehensive [API documentation](/api-docs/latest/).
-- Several [guides](/).
-- [Samples](https://github.com/stomp-js/samples/) for `@stomp/stompjs` and `@stompjs/rx-stomp`.
-- [Sample](https://github.com/stomp-js/rx-stomp-angular) for using `@stompjs/rx-stomp` with Angular.
+- Guides on the website home page.
+- [Samples](https://github.com/stomp-js/samples/) for `@stomp/stompjs` and `@stomp/rx-stomp`.
+- [Angular sample](https://github.com/stomp-js/rx-stomp-angular) for `@stomp/rx-stomp` with Angular.
diff --git a/_faqs/general-what-is-stomp.md b/_faqs/general-what-is-stomp.md
@@ -4,15 +4,11 @@ group: General
 priority: AAA
 ---
 
-[STOMP](https://stomp.github.io/index.html) is a simple text protocol to
-interact with messaging brokers.
-Usually, one of [AMQP](https://www.amqp.org/),
-[MQTT](http://mqtt.org/), [JMS](https://en.wikipedia.org/wiki/Java_Message_Service),
-or a similar protocol is used to connect to a messaging broker.
-In a language like JavaScript, it may not be easy to implement any of these protocols.
-So, STOMP becomes a reasonable option.
+[STOMP](https://stomp.github.io/index.html) is a simple text protocol for messaging brokers.
+Implementing broker-native protocols like [AMQP](https://www.amqp.org/),
+[MQTT](http://mqtt.org/), or [JMS](https://en.wikipedia.org/wiki/Java_Message_Service)
+in JavaScript can be complex; STOMP is a practical alternative.
 
-In addition, web browsers do not allow TCP connections from web pages.
-To overcome this limitation, 
-most of the brokers support STOMP over [WebSockets](https://en.wikipedia.org/wiki/WebSocket).
-The STOMP over WebSockets is referred to as WebStomp.
+Browsers do not allow raw TCP connections from web pages. To overcome this,
+many brokers support STOMP over [WebSocket](https://en.wikipedia.org/wiki/WebSocket),
+commonly called WebStomp.
diff --git a/_faqs/general-which-one-i-should-use-stompjs-rx-stomp-or-ng2-stompjs.md b/_faqs/general-which-one-i-should-use-stompjs-rx-stomp-or-ng2-stompjs.md
@@ -4,22 +4,16 @@ group: General
 priority: ACA
 ---
 
-`stompjs` is the underlying core library, usable almost everywhere.
+`stompjs` is the core library.
 
-`rx-stomp` exposes functionality as [RxJS] primitives.
-If you are already using RxJS in your project or are familiar with it, please consider using `rx-stomp`.
+`rx-stomp` exposes functionality as [RxJS] primitives. If you already use RxJS or prefer reactive
+streams, consider `rx-stomp`.
 
-Other than syntactical differences,
-these two variants have a very important difference.
-In `stompjs`, the [client] must only be used within the [onConnect] callback.
-Using it outside may produce strange errors.
-The `rx-stomp` does not suffer from this limitation.
+A key difference: with `stompjs`, use the [client] primarily inside the [onConnect] callback;
+using it outside can lead to races. `rx-stomp` avoids this limitation.
 
-So, as a rule of thumb, if your application needs to use the [client] object
-outside the [onConnect] callback, use `rx-stomp`.
-
-When using with Angular, `rx-stomp` seems natual as 
-Angular relies heavily on [RxJS].
+Rule of thumb: if you need to interact with the client outside the connect lifecycle,
+prefer `rx-stomp`. With Angular (which relies heavily on RxJS), `rx-stomp` feels natural.
 
 
 [RxJS]: https://github.com/ReactiveX/RxJS
diff --git a/_faqs/nodejs-can-this-library-be-used-with-nodejs.md b/_faqs/nodejs-can-this-library-be-used-with-nodejs.md
@@ -4,12 +4,10 @@ group: NodeJS
 priority: GAA
 ---
 
-Yes, NodeJS is supported using WebSockets as the communication mechanism.
-Please see [NodeJS topic in using StompJS guide](/guide/stompjs/using-stompjs-v5.html#in-nodejs).
-In addition, check the needed [PolyFills](/guide/stompjs/rx-stomp/polyfills-for-stompjs.html).
+Yes. Node.js is supported using WebSockets as the transport.
+See the guide: {% link _posts/2018-06-29-using-stompjs-v5.md %}
 
-While this library can be used with NodeJS, if your broker supports,
-you should consider
-[AMQP](https://www.amqp.org/) or
-[MQTT](http://mqtt.org/).
-These protocols are likely to give more flexibility than STOMP.
+Also ensure required polyfills are present: {% link _posts/2018-06-28-polyfills-for-stompjs.md %}
+
+If your broker supports them, you may also consider broker-native protocols like
+[AMQP](https://www.amqp.org/) or [MQTT](http://mqtt.org/).
diff --git a/_faqs/react-native-i-am-using-it-with-react-native-i-have-started-facing-strange-issues.md b/_faqs/react-native-i-am-using-it-with-react-native-i-have-started-facing-strange-issues.md
@@ -4,5 +4,9 @@ group: React Native
 priority: XAA
 ---
 
-Please see
-[React Native - Additional Notes](/workaround/stompjs/rx-stomp/react-native-additional-notes.html).
+The largest number of issues reported are related to React Native. These are platform/runtime limitations or environment problems — not bugs in this library.
+
+Please read and follow the React Native guide before reporting issues:
+- {% link _posts/2019-06-10-react-native-additional-notes.md %}
+
+This library requires specific workarounds to function correctly with React Native; the guide documents those steps. If problems persist after following the guide, include your RN version, platform (iOS/Android), relevant configuration, and logs when opening an issue.
diff --git a/_faqs/sockjs-i-am-using-sockjs-and-i-am-facing-issues-where-do-i-look.md b/_faqs/sockjs-i-am-using-sockjs-and-i-am-facing-issues-where-do-i-look.md
@@ -4,5 +4,4 @@ group: SockJS
 priority: EAE
 ---
 
-Several topics related to SockJS have been compiled at
-[Using STOMP with SockJS](/guide/stompjs/rx-stomp/using-stomp-with-sockjs.html).
+See the guide: {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}
diff --git a/_faqs/sockjs-i-am-using-sockjs-my-automatic-reconnection-does-not-work.md b/_faqs/sockjs-i-am-using-sockjs-my-automatic-reconnection-does-not-work.md
@@ -4,11 +4,9 @@ group: SockJS
 priority: EAC
 ---
 
-You need to pass a factory that returns a SockJS instance.
+Pass a `webSocketFactory` that creates a new SockJS instance for each (re)connect.
 
-Please see
-[Using STOMP with SockJS](/guide/stompjs/rx-stomp/using-stomp-with-sockjs.html)
-if you are using recent versions of these libraries.
+See: {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}
 
-If you are using `Stomp.over` compatibility mode (or older version), please refer to
+If you are using the legacy `Stomp.over` compatibility API, refer to
 [Stomp.over API docs](/api-docs/latest/classes/Stomp.html#over).
diff --git a/_faqs/sockjs-is-sockjs-needed-to-use-these-libraries.md b/_faqs/sockjs-is-sockjs-needed-to-use-these-libraries.md
@@ -4,8 +4,9 @@ group: SockJS
 priority: EAA
 ---
 
-No SockJS is not mandatory to use this library.
+No. SockJS is optional.
 
-SockJS, however, is supported.
-Please see
-[using StompJS with SockJS](/guide/stompjs/rx-stomp/using-stomp-with-sockjs.html).
+Prefer native WebSockets by default. Use SockJS only to support environments without WebSocket,
+or when your deployment requires HTTP-only transport.
+
+See: {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}
