Skip to content

Repository navigation

v83-upgrade-notes.md

Latest commit

 

History

History
241 lines (174 loc) · 7.64 KB

v83-upgrade-notes.md

File metadata and controls

241 lines (174 loc) · 7.64 KB
Raw

Hoist React v83 Upgrade Notes

From: v82.x → v83.0.0 | Released: 2026-03-xx | Difficulty: 🟢 LOW

Overview

Hoist React v83 is a major release paired with hoist-core v37. The headline addition is client-side distributed tracing via TraceService, providing OTEL-based end-to-end observability across browser and server. Traced exceptions now include a traceId for correlation with server-side traces, displayed in both error dialogs and toasts. This release also introduces the static defaults pattern for app-level configuration overrides across several core models, new SegmentedControl and CheckboxButton input components, and Admin Console support for opt-in metrics publishing.

The downloadjs third-party dependency has been removed and replaced with built-in utilities. Apps that imported downloadjs directly (relying on it as a transitive hoist-react dependency) must update those usages.

Apps should also take the opportunity to migrate deprecated static properties to the new ModelClassName.defaults pattern (scheduled for removal in v85).

Prerequisites

Before starting, ensure:

  • Running hoist-react v82.x
  • hoist-core upgraded to >= v37.0 (required — TraceService and metrics publishing depend on new server-side infrastructure)

Upgrade Steps

1. Update hoistCoreVersion in gradle.properties

Hoist React v83 requires hoist-core >= v37.0.

File: gradle.properties

Before:

hoistCoreVersion=36.3.1

After:

hoistCoreVersion=37.0.0

2. Update package.json

Bump hoist-react to v83.

File: package.json

Before:

"@xh/hoist": "~82.0.3"

After:

"@xh/hoist": "~83.0.0"

Then run yarn install or npm install to update dependencies.

3. Migrate Deprecated Static Properties to static defaults (recommended)

Several models previously exposed ad-hoc static properties for app-level configuration (e.g. GridModel.DEFAULT_AUTOSIZE_MODE). These have been replaced by a unified static defaults pattern. The old properties still function but log deprecation warnings and are scheduled for removal in v85.

Find affected files:

grep -rE "GridModel\.(DEFAULT_AUTOSIZE_MODE|DEFAULT_RESTORE_DEFAULTS_WARNING|defaultContextMenu)|ChartModel\.defaultContextMenu|ExceptionHandler\.(REDACT_PATHS|ALERT_TYPE|TOAST_PROPS)|FetchService\.(autoGenCorrelationIds|genCorrelationId|correlationIdHeaderKey)" client-app/src/

GridModel

Before:

import {GridModel} from '@xh/hoist/cmp/grid';

GridModel.DEFAULT_AUTOSIZE_MODE = 'managed';
GridModel.DEFAULT_RESTORE_DEFAULTS_WARNING = 'Reset all grid settings?';

After:

import {GridModel} from '@xh/hoist/cmp/grid';

GridModel.defaults.autosizeMode = 'managed';
GridModel.defaults.restoreDefaultsWarning = 'Reset all grid settings?';

See GridModelDefaults for the full set of available defaults including cellBorders, colChooserModel, contextMenu, enableColumnPinning, enableExport, rowBorders, showGroupRowCounts, sizingMode, stripeRows, and more.

ChartModel

Before:

import {ChartModel} from '@xh/hoist/cmp/chart';

const menu = ChartModel.defaultContextMenu;

After:

import {ChartModel} from '@xh/hoist/cmp/chart';

const menu = ChartModel.defaults.contextMenu;

ExceptionHandler

Before:

import {ExceptionHandler} from '@xh/hoist/core';

ExceptionHandler.ALERT_TYPE = 'toast';
ExceptionHandler.TOAST_PROPS = {timeout: 5000};

After:

import {ExceptionHandler} from '@xh/hoist/core';

ExceptionHandler.defaults.alertType = 'toast';
ExceptionHandler.defaults.toastProps = {timeout: 5000};

FetchService

Before (in Bootstrap.ts):

import {FetchService} from '@xh/hoist/svc';

FetchService.autoGenCorrelationIds = true;

After:

import {FetchService} from '@xh/hoist/svc';

FetchService.defaults.autoGenCorrelationIds = true;

4. Replace downloadjs Imports (if applicable)

The downloadjs third-party package has been removed from hoist-react's dependencies. Hoist itself has migrated to new built-in utilities. If your app imported downloadjs directly (relying on it as a transitive dependency of hoist-react), you must replace those usages with the new downloadBlob() or downloadViaUrl() utilities from @xh/hoist/utils/js.

Find affected files:

grep -rE "from 'downloadjs'|from \"downloadjs\"|require\('downloadjs'\)" client-app/src/

Before:

import download from 'downloadjs';

const blob = await response.blob();
download(blob, 'export.xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');

After:

import {downloadBlob} from '@xh/hoist/utils/js';

const blob = await response.blob();
downloadBlob(blob, 'export.xlsx');

For URL-based downloads (where you have a URL rather than a Blob):

import {downloadViaUrl} from '@xh/hoist/utils/js';

downloadViaUrl('/api/export/report', 'report.pdf');

Note that these utilities do not require a content type parameter — the browser infers the type from the Blob or URL.

5. Migrate Deprecated Filter Utilities (recommended)

If you have not yet migrated from the deprecated standalone filter utilities (withFilterByField, withFilterByKey, replaceFilterByKey, withFilterByTypes), do so now. These were deprecated in v82 and are scheduled for removal in v85. See the v82 upgrade notes for detailed before/after examples.

Find affected files:

grep -rE "withFilterByField|withFilterByKey|replaceFilterByKey|withFilterByTypes" client-app/src/

6. Consider SegmentedControl as a ButtonGroupInput Alternative (optional)

v83 introduces SegmentedControl, a new desktop input component for mutually exclusive option sets. It provides stronger visual differentiation of the active selection compared to ButtonGroupInput and is well-suited for small, fixed option groups (e.g. sizing modes, view toggles, status filters).

This is not a required migration — ButtonGroupInput remains fully supported. However, if your app uses ButtonGroupInput for small toggle groups, SegmentedControl may be a worthwhile improvement worth exploring.

Find potential candidates:

grep -rE "buttonGroupInput|ButtonGroupInput" client-app/src/

Review each usage and consider whether the use case is a small set of mutually exclusive options that would benefit from the segmented control style. SegmentedControl supports the same bind pattern as other Hoist inputs and works with both model binding and onChange callbacks.

Verification Checklist

After completing all steps:

  • hoistCoreVersion in gradle.properties is >= 37.0.0
  • yarn install / npm install completes without errors
  • yarn lint / npm run lint passes (or only pre-existing warnings remain)
  • npx tsc --noEmit passes
  • Application loads without console errors
  • No downloadjs imports remain: grep -rE "from 'downloadjs'|from \"downloadjs\"" client-app/src/
  • No deprecated static property warnings in console: grep -rE "DEFAULT_AUTOSIZE_MODE|DEFAULT_RESTORE_DEFAULTS_WARNING|defaultContextMenu|REDACT_PATHS|ALERT_TYPE|TOAST_PROPS" client-app/src/
  • No deprecated filter utilities remain: grep -rE "withFilterByField|withFilterByKey|replaceFilterByKey|withFilterByTypes" client-app/src/
  • Grids, charts, and dashboards render correctly
  • Admin Console Metrics tab loads (if hoist-core v37+ with metrics configured)

Reference