@xh/hoist 75.0.0-SNAPSHOT.1753722797428 → 75.0.0-SNAPSHOT.1753726213836

package/CHANGELOG.md

@@ -37,6 +37,10 @@
 
 ### ⚙️ Technical
 
+* WebSockets are now enabled by default for client apps, as they have been on the server since Hoist
+  Core v20.2. Maintaining a WebSocket connection back to the Hoist server enables useful Admin
+  Console functionality and is recommended, but clients that must disable WebSockets can do so via
+  `AppSpec.disableWebSockets`. Note `AppSpec.enableWebSockets` is deprecated and can be removed.
 * Hoist now sets a reference to an app's singleton `AuthModel` on a static `instance` property of
   the app-specified class. App developers can declare a typed static `instance` property on their
   model class and use it to access the singleton with its proper type, vs. `XH.authModel`.

package/build/types/core/AppSpec.d.ts

@@ -1,4 +1,4 @@
-import { HoistAppModel, HoistAuthModel, ElementFactory, HoistProps } from '@xh/hoist/core';
+import { ElementFactory, HoistAppModel, HoistAuthModel, HoistProps } from '@xh/hoist/core';
 import { Component, ComponentClass, FunctionComponent } from 'react';
 /**
  * Spec for a client-side Hoist application. A config matching this class's shape is provided
@@ -50,6 +50,13 @@ export declare class AppSpec<T extends HoistAppModel = HoistAppModel> {
      * either `@xh/hoist/desktop/AppContainer` or `@xh/hoist/mobile/AppContainer`.
      */
     containerClass: ComponentClass<HoistProps> | FunctionComponent<HoistProps>;
+    /**
+     * True to disable Hoist's built-in WebSocket support for this client app. Even if the app
+     * itself is not using WebSockets for business data, the Hoist Admin Console's "Clients" tab and
+     * related functionality benefit from having them enabled, so disable only if there is a good
+     * reason to do so.
+     */
+    disableWebSockets?: boolean;
     /**
      * True to disable Field-level XSS protection by default across all Stores/Fields in the app.
      * For use with secure, internal apps that do not display arbitrary/external user input and
@@ -102,15 +109,16 @@ export declare class AppSpec<T extends HoistAppModel = HoistAppModel> {
      *  initialized, including a breakdown of elapsed time throughout the init process.
      */
     trackAppLoad?: boolean;
-    /** True to enable Hoist websocket connectivity. */
+    /** @deprecated - use {@link AppSpec.disableWebSockets} instead. */
     webSocketsEnabled?: boolean;
-    constructor({ authModelClass, checkAccess, clientAppCode, clientAppName, componentClass, containerClass, disableXssProtection, enableLoginForm, enableLogout, idlePanel, isMobileApp, lockoutMessage, lockoutPanel, loginMessage, modelClass, showBrowserContextMenu, trackAppLoad, webSocketsEnabled }: {
+    constructor({ authModelClass, checkAccess, clientAppCode, clientAppName, componentClass, containerClass, disableWebSockets, disableXssProtection, enableLoginForm, enableLogout, idlePanel, isMobileApp, lockoutMessage, lockoutPanel, loginMessage, modelClass, showBrowserContextMenu, trackAppLoad, webSocketsEnabled }: {
         authModelClass?: typeof HoistAuthModel;
         checkAccess: any;
         clientAppCode?: string;
         clientAppName?: string;
         componentClass: any;
         containerClass: any;
+        disableWebSockets?: boolean;
         disableXssProtection?: boolean;
         enableLoginForm?: boolean;
         enableLogout?: boolean;
@@ -122,6 +130,6 @@ export declare class AppSpec<T extends HoistAppModel = HoistAppModel> {
         modelClass: any;
         showBrowserContextMenu?: boolean;
         trackAppLoad?: boolean;
-        webSocketsEnabled?: boolean;
+        webSocketsEnabled: any;
     });
 }

package/build/types/svc/WebSocketService.d.ts

@@ -24,14 +24,14 @@ import { HoistService, PlainObject } from '@xh/hoist/core';
  */
 export declare class WebSocketService extends HoistService {
     static instance: WebSocketService;
-    readonly HEARTBEAT_TOPIC = "xhHeartbeat";
     /** Check connection and send a new heartbeat (which should be promptly ack'd) every 10s. */
+    readonly HEARTBEAT_TOPIC = "xhHeartbeat";
     readonly HEARTBEAT_INTERVAL: number;
     readonly REG_SUCCESS_TOPIC = "xhRegistrationSuccess";
     readonly FORCE_APP_SUSPEND_TOPIC = "xhForceAppSuspend";
     readonly REQ_CLIENT_HEALTH_RPT_TOPIC = "xhRequestClientHealthReport";
     readonly METADATA_FOR_HANDSHAKE: string[];
-    /** True if WebSockets generally enabled - set statically in code via {@link AppSpec}. */
+    /** True if WebSockets not explicitly disabled via {@link AppSpec.disableWebSockets}. */
     enabled: boolean;
     /** Unique channel assigned by server upon successful connection. */
     channelKey: string;

package/core/AppSpec.ts

@@ -4,9 +4,9 @@
  *
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
-import {XH, HoistAppModel, HoistAuthModel, ElementFactory, HoistProps} from '@xh/hoist/core';
-import {throwIf} from '@xh/hoist/utils/js';
-import {isFunction, isNil, isString} from 'lodash';
+import {ElementFactory, HoistAppModel, HoistAuthModel, HoistProps, XH} from '@xh/hoist/core';
+import {apiDeprecated, throwIf} from '@xh/hoist/utils/js';
+import {isFunction, isNil, isString, isUndefined} from 'lodash';
 import {Component, ComponentClass, FunctionComponent} from 'react';
 
 /**
@@ -62,6 +62,14 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
      */
     containerClass: ComponentClass<HoistProps> | FunctionComponent<HoistProps>;
 
+    /**
+     * True to disable Hoist's built-in WebSocket support for this client app. Even if the app
+     * itself is not using WebSockets for business data, the Hoist Admin Console's "Clients" tab and
+     * related functionality benefit from having them enabled, so disable only if there is a good
+     * reason to do so.
+     */
+    disableWebSockets?: boolean;
+
     /**
      * True to disable Field-level XSS protection by default across all Stores/Fields in the app.
      * For use with secure, internal apps that do not display arbitrary/external user input and
@@ -125,7 +133,7 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
      */
     trackAppLoad?: boolean;
 
-    /** True to enable Hoist websocket connectivity. */
+    /** @deprecated - use {@link AppSpec.disableWebSockets} instead. */
     webSocketsEnabled?: boolean;
 
     constructor({
@@ -135,6 +143,7 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
         clientAppName = XH.appName,
         componentClass,
         containerClass,
+        disableWebSockets = false,
         disableXssProtection = false,
         enableLoginForm = false,
         enableLogout = false,
@@ -146,7 +155,7 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
         modelClass,
         showBrowserContextMenu = false,
         trackAppLoad = true,
-        webSocketsEnabled = false
+        webSocketsEnabled
     }) {
         throwIf(!componentClass, 'A Hoist App must define a componentClass');
 
@@ -164,12 +173,24 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
             'A Hoist App must specify a required role string or a function for checkAccess.'
         );
 
+        if (!isUndefined(webSocketsEnabled)) {
+            let msg: string;
+            if (webSocketsEnabled === false) {
+                disableWebSockets = true;
+                msg = `Specify disableWebSockets: true to continue actively disabling WebSockets if required.`;
+            } else {
+                msg = `WebSockets are now enabled by default - this property can be safely removed from your appSpec.`;
+            }
+            apiDeprecated('webSocketsEnabled', {msg, v: 'v78'});
+        }
+
         this.authModelClass = authModelClass;
         this.checkAccess = checkAccess;
         this.clientAppCode = clientAppCode;
         this.clientAppName = clientAppName;
         this.componentClass = componentClass;
         this.containerClass = containerClass;
+        this.disableWebSockets = disableWebSockets;
         this.disableXssProtection = disableXssProtection;
         this.enableLoginForm = enableLoginForm;
         this.enableLogout = enableLogout;
@@ -181,6 +202,6 @@ export class AppSpec<T extends HoistAppModel = HoistAppModel> {
         this.modelClass = modelClass;
         this.showBrowserContextMenu = showBrowserContextMenu;
         this.trackAppLoad = trackAppLoad;
-        this.webSocketsEnabled = webSocketsEnabled;
+        this.webSocketsEnabled = !disableWebSockets;
     }
 }

package/core/XH.ts

@@ -386,7 +386,6 @@ export class XHApi {
             clientAppCode: 'admin',
             clientAppName: `${this.appName} Admin`,
             isMobileApp: false,
-            webSocketsEnabled: true,
             checkAccess: 'HOIST_ADMIN_READER',
             ...appSpec
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "75.0.0-SNAPSHOT.1753722797428",
+  "version": "75.0.0-SNAPSHOT.1753726213836",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",

package/svc/WebSocketService.ts

@@ -38,8 +38,8 @@ import {find, pull} from 'lodash';
 export class WebSocketService extends HoistService {
     static instance: WebSocketService;
 
-    readonly HEARTBEAT_TOPIC = 'xhHeartbeat';
     /** Check connection and send a new heartbeat (which should be promptly ack'd) every 10s. */
+    readonly HEARTBEAT_TOPIC = 'xhHeartbeat';
     readonly HEARTBEAT_INTERVAL = 10 * SECONDS;
 
     readonly REG_SUCCESS_TOPIC = 'xhRegistrationSuccess';
@@ -47,8 +47,8 @@ export class WebSocketService extends HoistService {
     readonly REQ_CLIENT_HEALTH_RPT_TOPIC = 'xhRequestClientHealthReport';
     readonly METADATA_FOR_HANDSHAKE = ['appVersion', 'appBuild', 'loadId', 'tabId'];
 
-    /** True if WebSockets generally enabled - set statically in code via {@link AppSpec}. */
-    enabled: boolean = XH.appSpec.webSocketsEnabled;
+    /** True if WebSockets not explicitly disabled via {@link AppSpec.disableWebSockets}. */
+    enabled: boolean = !XH.appSpec.disableWebSockets;
 
     /** Unique channel assigned by server upon successful connection. */
     @observable channelKey: string = null;
@@ -84,7 +84,7 @@ export class WebSocketService extends HoistService {
         const {environmentService} = XH;
         if (environmentService.get('webSocketsEnabled') === false) {
             this.logError(
-                `WebSockets enabled on this client app but disabled on server. Adjust your server-side config.`
+                `WebSockets enabled on this client app but disabled on server - unexpected! WebSockets will not be available, review and reconcile your server configuration.`
             );
             this.enabled = false;
             return;