Hoist applications are built on a pairing of hoist-react (client) and hoist-core (server), plus hoist-dev-utils (the Webpack build tooling consumed by apps as a devDependency). These libraries evolve together but are versioned independently. Running a mismatched combination can cause failures that are difficult to diagnose — error messages typically don't indicate a version mismatch. hoist-core mismatches surface at runtime; hoist-dev-utils mismatches surface at build / dev-server time.
This document provides a single reference for which hoist-core and hoist-dev-utils versions are required, recommended, or tested with each hoist-react release.
Update this document whenever a new hoist-react major version is released or a new hoist-core dependency is introduced. Use the following checklist:
- Add a new row to the Compatibility Matrix with the new hoist-react version
- Set Min Core Required if the release introduces a hard dependency on a new core version
(check the CHANGELOG for "Requires hoist-core" entries). If this value changes, update
MIN_HOIST_CORE_VERSIONincore/XH.tsto match - that constant is what actually enforces the minimum at runtime, and it is easy to miss. See Min Core Required. - Set Recommended Core if the release has features that benefit from a newer core version but don't strictly require it
- Set Max Core Tested to the highest hoist-core version verified at the time of release
- Update the Reverse Lookup table if the new core version introduces breaking changes for older hoist-react versions
- Update the hoist-react ↔ hoist-dev-utils tables if the release requires or recommends a new dev-utils version, or if a new dev-utils major has been released (check both CHANGELOGs for "Requires hoist-react" / "Requires ... hoist-dev-utils" entries)
- Link to upgrade notes if available
Template row:
| XX.0 | -- | | YY.x | [Upgrade notes](./upgrade-notes/vXX-upgrade-notes.md) |The compatibility matrix uses three requirement levels:
| Level | Meaning |
|---|---|
| Min Core Required | Hard minimum — the app won't function below this hoist-core version. hoist-core does not guarantee backward-compatible APIs, so this is a real constraint. Enforced at startup by EnvironmentService, which throws when the server reports a version below MIN_HOIST_CORE_VERSION (core/XH.ts). This column and that constant must agree. |
| Recommended Core | Features available only with this core version or higher, but not a hard gate for basic operation. |
| Max Core Tested | The highest hoist-core version verified with this hoist-react release. Running a newer core is untested and could introduce incompatibilities. |
Conventions:
--in Min Core Required means "unchanged from the previous version — scan down the table to find the last explicitly stated minimum."- Max Core Tested represents the known-good ceiling. Developers running a core version above this should upgrade hoist-react to the version tested with that core.
Verified against both hoist-react and hoist-core changelogs.
| hoist-react | Min Core Required | Recommended Core | Max Core Tested | Notes | Upgrade |
|---|---|---|---|---|---|
| 87.0 | 40.5.0 | 41.0 | 41.0 | ViewManager group rename + bulk edit (40.5); directory group names/search, tabbed config editor (41, degrade gracefully) |
Notes |
| 86.0 | -- | 40.0.1 | 40.0.1 | Client MetricsService, Runner API, remote-traceparent spans |
Notes |
| 85.0 | -- | 39.0 | 39.0 | Nested app-load spans, InitContext, name-based sampleRules |
Notes |
| 84.0 | 38.0 | 38.0 | Span sampling, OTEL tag alignment, log level overrides | Notes | |
| 83.0 | 37.0 | 37.0 | OTEL tracing, static defaults, metrics publishing | Notes | |
| 82.0 | -- | 36.3 | 36.3 | Admin Metrics tab | Notes |
| 81.0 | 36.1 | 36.2 | Efficient identity init | Notes | |
| 80.0 | -- | 36.0 | Notes | ||
| 79.0 | -- | 35.0 | 35.0 | clientAppCode tracking, log file deletion |
Notes |
| 78.0 | -- | 34.x | Notes | ||
| 77.x | -- | 33.x | Highcharts v12 (client-only) | Notes | |
| 76.0 | -- | 32.0 | 32.0 | View visibility editing, basic view state | Notes |
| 75.0 | -- | 31.x | WebSockets enabled by default | Notes | |
| 74.x | -- | 31.x | ViewManager improvements | Notes | |
| 73.0 | 31.0 | 31.0 | Consolidated Admin Clients tab, TrackLog properties | Notes | |
| 72.1 | -- | 28.1 | 28.1 | JSON Search in Admin Console | |
| 72.0 | -- | 28.0 | Mobile Navigator rebuild | ||
| 71.0 | 27.0 | 27.0 | ViewManager, cluster state monitoring | ||
| 70.0 | -- | 26.x | ViewManager, persistence improvements | ||
| 69.0 | 24.0 | 24.0 | Activity tracking batch upload, memory monitoring | ||
| 68.0 | 22.0 | 22.0 | Consolidated Alert Banner polling | ||
| 67.0 | 21.0 | 21.0 | CachedValue (replaces ReplicatedValue) | ||
| 66.x | -- | 20.x | HoistAuthModel introduction | ||
| 65.0 | -- | 20.x | hoist-dev-utils >= 9 | ||
| 64.0 | 20.0 | 20.0 | Multi-instance clustering, AG Grid 31 | ||
| 63.0 | 19.0 | 19.0 | Activity/client error tracking APIs, Blueprint 5 | ||
| 62.0 | -- | 18.x | hoist-dev-utils >= 8 | ||
| 61.0 | -- | 18.4 | 18.4 | Config override display in Admin Console | |
| 60.0 | 18.0 | 18.0 | Role Management system | ||
| 59.0 | -- | 17.2 | 17.2 | JDBC connection pool monitoring | |
| 58.0 | -- | 16.4 | 16.4 | forceReload version check, TrackOptions.logData |
|
| 57.0 | -- | 16.3 | 16.3 | Alert banner presets, HOIST_IMPERSONATOR role | |
| 56.0 | 16.0 | 16.0 | AG Grid 29, local prefs migration |
Derived from changelog entries. Core version requirements may be approximate.
| hoist-react | Min Core Required | Recommended Core | Max Core Tested | Notes |
|---|---|---|---|---|
| 53.0 | 14.4 | 14.4 | HOIST_ADMIN_READER role | |
| 50.0 | 14.0 | 14.0 | Excel export with FieldType | |
| 48.0 | -- | 13.2 | 13.2 | Admin log file metadata |
| 44.0 | 10.0 | 10.0 | JsonBlobService APIs, Alert Banner endpoints | |
| 36.1 | 8.3 | 8.3 | JsonBlobService, Admin Activity/Error tracking | |
| 35.0 | 8.0 | 8.0 | Admin Activity Tracking tab | |
| 26.0 | ~6.1 | 6.1 | WebSocket support | |
| 15.0 | 5.0 | 5.0 | Role loading, authentication changes | |
| 5.0 | 3.0 | 3.0 | Multi-environment config unwinding |
Since hoist-core does not guarantee backward compatibility with older hoist-react versions, upgrading core without upgrading react can break things — not just miss features. Use this table to find the minimum hoist-react version for a given core release.
| hoist-core | Min hoist-react | Notes |
|---|---|---|
| 41.0 | 87.0 recommended | Tabbed/typed config editor, directory group names + search endpoints - consumed by v87's Admin Console, which degrades gracefully without them. No hard hoist-react bump. |
| 40.5 | 87.0 recommended | ViewManager group rename + bulk-editing endpoints consumed by v87 (which requires 40.5 as its floor). No hard hoist-react bump from 40.0. |
| 40.0 | 86.0 recommended | Client metrics /xh/recordMetrics endpoint (added in 40.0.1). No hard hoist-react bump; needed only by apps recording client metrics. |
| 39.0 | 85.0 recommended | Telemetry package restructuring, typed ConfigSpec/PreferenceSpec/RoleSpec, JDK 25 toolchain. No hard hoist-react bump from 38.0; v85 is the natural pairing. |
| 38.0 | 84.0 | Span sampling, OTEL tag alignment, log level overrides |
| 37.0 | 83.0 | OTEL tracing, metrics publishing |
| 36.3 | 82.0 recommended | Admin Metrics tab |
| 36.1 | 81.0 | Efficient identity init |
| 35.0 | 79.0 recommended | clientAppCode, log file deletion |
| 32.0 | 76.0 recommended | View state, visibility editing |
| 31.0 | 73.0 | Consolidated Admin Clients tab, TrackLog properties |
| 28.1 | 72.1 recommended | JSON Search in Admin Console |
| 27.0 | 71.0 | ViewManager, cluster state monitoring |
| 24.0 | 69.0 | Activity tracking batch upload |
| 22.0 | 68.0 | Consolidated Alert Banner polling |
| 21.0 | 67.0 | CachedValue |
| 20.0 | 64.0 | Multi-instance clustering |
| 19.0 | 63.0 | Activity/client error tracking APIs |
| 18.0 | 60.0 | Role Management system |
| 16.0 | 56.0 | AG Grid 29, local prefs migration |
| 14.4 | 53.0 | HOIST_ADMIN_READER role |
| 14.0 | 50.0 | Excel export with FieldType |
| 10.0 | 44.0 | JsonBlobService APIs |
| 8.0 | 35.0 | Admin Activity Tracking tab |
hoist-dev-utils is a build-time dependency: it supplies the Webpack config that compiles both app
code and hoist-react's raw TypeScript source. A version mismatch therefore fails at build or
dev-server startup (pnpm start / pnpm build, or the yarn equivalents) rather than at runtime.
Requirements flow in both directions - dev-utils majors set a minimum hoist-react, and some
hoist-react releases require or strongly recommend a newer dev-utils.
Same conventions as the core matrix above: -- means "unchanged from the previous version - scan
down to the last explicitly stated value."
Unlike hoist-core minimums (hard runtime gates), dev-utils minimums here reflect the oldest pairing XH supports and tests with that hoist-react release - older dev-utils may happen to build, but such pairings are untested and unsupported. dev-utils is a build-time-only devDependency, so taking its current major alongside a hoist-react upgrade is low-cost and always the right move.
| hoist-react | Min Dev-Utils Required | Recommended Dev-Utils | Notes |
|---|---|---|---|
| 87.0 | 14.0 | 14.0 | React 19: dev-utils 14 ships @types/react 19.x and is required for apps adopting pnpm. (13.x can build v87 with @types/react 19.x pinned via resolutions - a transitional pairing only, not supported.) |
| 86.0 | -- | 13.0.1 | dev-utils 13 sets a Node floor of >= 22.11 and swaps the markdown loader - verify flex: 1 1 0 styles (see v86 notes). |
| 83.0 | -- | 12.0 | dev-utils 12's same-port dev proxy pairs with the hoist-react 83.0.2 WebSocketService fix. |
| 73.0 | -- | 11.0 | Strongly recommended pairing; brings eslint 9 / @xh/eslint-config 7 (app eslint config migration). |
| 71.0 | -- | 10.0 | dev-utils 10 sets its minimum at hoist-react 71. |
| 66.1 | 9.0.1 | type-fest required for TS compile. |
|
| 65.0 | 9.0 | Static assets moved to /public. |
|
| 62.0 | 8.0 |
Minimum hoist-react version (and Node floor, where declared) for each dev-utils major. These are hard gates stated in the hoist-dev-utils CHANGELOG.
| hoist-dev-utils | Min hoist-react | Min Node | Notes |
|---|---|---|---|
| 14.0 | 87.0 | 22.15 | React 19 / @types/react 19.x baseline. Adds pnpm support - apps adopting pnpm must take 14+, and must declare every package they import directly (see dev-utils CHANGELOG). webpack-dev-server 6. |
| 13.0 | -- | 22.11 | Take 13.0.1+. Markdown files now import as strings; verify flex: 1 1 0 styles. |
| 12.0 | 83.0.2 | Same-port dev proxy (baseUrl default now /api/); requires hoist-react's WebSocketService fix in 83.0.2. |
|
| 11.0 | 73.0 | @xh/eslint-config 7 requires app eslint config migration (flat config). |
|
| 10.0 | 71.0 | ||
| 9.0 | 64.1 | Static assets in /public; 9.0.1 adds type-fest (needed by hoist-react 66.1+). |
A brief orientation to the major epochs of hoist-react / hoist-core development:
- Modern Era (v64+, core v20+): Multi-instance clustering, ViewManager, Java 17+, AG Grid v31+, HoistAuthModel, Blueprint 5→6. Active support with upgrade notes for each major version.
- Middle Era (v44–v63, core v10–v19): JsonBlobService, Role Management system, AG Grid maturation (v28→v29), DashCanvas, Persistence API, TypeScript migration.
- Early Era (v5–v43, core v3–v9): Foundational authentication, WebSocket support, Activity Tracking, initial AG Grid and Blueprint integration.
Error messages from a version mismatch typically don't indicate the root cause. Symptoms range from missing API endpoints (404 errors) to subtle data format incompatibilities. Always check this matrix before investigating other causes.
A required core version is a hard gate — the app will not function without it. A recommended core version unlocks specific features but the app will run without it. Check the CHANGELOG or upgrade notes for details on what each recommended version enables.
Some hoist-react upgrades also require a corresponding hoist-dev-utils upgrade, and each dev-utils major sets its own minimum hoist-react. These are build-time dependencies, so failures appear when starting the dev server or building rather than at runtime. See hoist-react ↔ hoist-dev-utils above.
hoist-core does not guarantee backward-compatible APIs with older hoist-react versions. Upgrading core can break things, not just miss features. Always consult the Reverse Lookup table and plan to upgrade both libraries together.
- hoist-react CHANGELOG — version history and release notes
- hoist-core CHANGELOG — server-side version history
- hoist-dev-utils CHANGELOG — build tooling version history
- Upgrade Notes — step-by-step guides for major version upgrades