TrizTech/ohif-viewer
17
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Update to use pnpm (#6031)

Browse Source 
* Initial pnpm change

* Install/update in pnpm sort of works

* Attempt to fix install

* fix pnpm

* Refactor build process to use RSPack instead of Webpack across multiple extensions and modes. Update package.json scripts for development and production builds, and adjust webpack configuration files to accommodate new plugin imports and settings.

* Update RSPack dependencies to version 2.0.0 across the project, enhancing compatibility and performance. Refactor webpack configuration in multiple extensions and modes to utilize the new library structure for UMD output. Adjust package.json scripts and settings for improved build processes.

* Implement migration guide for OHIF 3.13, detailing the transition from Webpack to Rspack v2, the shift to pnpm workspaces, and the increase in minimum Node.js version to 24. Include new build commands, plugin replacements, and updates to package configurations across the monorepo.

* Fix some dev:fast bugs

* Move netlify to top level and remove webpack builds

* Update version script to deal with lerna missing

* chore(tests): Update multiple screenshot test images for various specs

* feat(screenshot-reviewer): Add screenshot review tool and update package.json scripts

* fix(DICOMSRDisplayTool): Improve actor presence check in viewport

* chore(tests): Update multiple screenshot assets for various specs

* chore(tests): Integrate waitForPaintToSettle and waitForViewportsRendered in multiple specs for improved rendering stability

* chore(tests): Update screenshot assets for SEGHydration and SEGNoHydration specs

* test: update progressive loading screenshots

* jest 30 test fixes for compatibility with pnpm cs3d

* Use correct setDisplaySets instead of setDataId

* fix: Naming change for LegacyVolumeViewport3D

* Update to allow tolerance for contour tests

* update

* fix

* refactor: Replace instanceof checks with utility functions for viewport type validation

* fix: Update createSegmentationForViewport to handle undefined displaySetInstanceUID gracefully

* bun lock

* chore(pnpm): align workspace setup to cornerstone3D and address PR review

- .npmrc / pnpm-workspace.yaml: mirror cs3d (node-linker hoisted,
  strict-peer-dependencies=false, link/prefer workspace packages,
  minimumReleaseAge, frozenLockfile); sync axios 1.17.0 + tmp override
- root: packageManager pnpm@11.4.0, engines pnpm >=11, wire preinstall.js
- restore preinstall.js (token/private-repo + CLAUDE->AGENTS symlink)
- playwright.yml: keep base CS3D-integration workflow, switch only the
  package manager (bun/yarn -> pnpm) and node 20 -> 24
- webpack.base.js: revert prod devtool to source-map (drop hidden-source-map)
- remove @percy/cypress; .netlify + cli templates engines pnpm >=11
- Dockerfile pin pnpm@11; document tests/globalSetup.ts warmup
- drop dicom-sr -> measurement-tracking edge (breaks pnpm cyclic dep)

* chore(pnpm): regenerate lockfile and restore cs3d:* dev scripts

- Regenerate pnpm-lock.yaml against the resolved workspace (cycle removed,
  cs3d 4.22.10, workspace:* internal deps).
- Restore cs3d:checkout/check/build/watch/install/link/unlink helper scripts
  (dropped when taking the PR's root scripts), converted yarn -> pnpm since
  the local cornerstone3D checkout is now pnpm too.

* Merge base branch issues

* Link ohif app

* ci: pin pnpm to 11.4.0 in action-setup (was version: latest)

version: latest floats across runs and breaks reproducibility. Pin to the repo's packageManager version (pnpm@11.4.0) in both playwright and build-docs workflows.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: Accidental commit of .npmrc config

* Fix build issues

* build fix

* Dependency fixes

* fix: Dependency bug in app on extensions/modes

* Fix output configuration

* Replace percy screenshots with native cypress

* Remove percy screenshot entirely

* fix: Build issues

* force click to prevent canvas cover issues

* Enable swiftshader

* Update launch of electron

* fix: Broken size calculation

* Empty change to force a re-build

* fix(cypress): generate ui-next tailwind classes; drop unsupported electron arg

Tailwind only scanned @ohif/ui-next via ../../node_modules/@ohif/ui-next, which no longer resolves under the pnpm layout, so ui-next-unique classes (e.g. toolbar split-button sizing) were never generated. Those buttons' hit-boxes collapsed, producing Cypress 'covered by element' failures on toolbar interactions. Scan ui-next by direct filesystem path like ui/extensions/modes.

Also stop pushing --enable-unsafe-swiftshader into Electron's launchOptions.args (Electron ignores it and warns); it is supplied via ELECTRON_EXTRA_LAUNCH_ARGS in CI. The arg is still pushed for non-electron chromium (local chrome).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(e2e): disable dev-server overlay during coverage runs

The rspack dev-server client overlay injects an iframe (id=rspack-dev-server-client-overlay) that intercepts pointer events, causing Playwright/Cypress clicks on toolbar buttons to time out (e.g. MicroscopyPanel). Disable the overlay when COVERAGE=true (e2e/Playwright webServer) while keeping it for normal local dev.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(microscopy): provide dicom-microscopy-viewer runtime assets

The microscopy viewer is loaded at runtime via peerImport('dicom-microscopy-viewer'), which fetches the copied asset served at /dicom-microscopy-viewer/. Two issues prevented those assets from reaching dist, so the viewer never initialized and drawing produced no measurement row:

1) dicom-microscopy-viewer was declared in no workspace package.json (only under libs/@cornerstonejs), so it was not installed at root node_modules and the pluginConfig copy source did not exist. Declare it (0.48.6, matching libs) in the microscopy extension.

2) createCopyPluginToDist appended the public/dist folder name to entries that specify an explicit directory, breaking the dicom-microscopy-viewer public entry (looked for .../dynamic-import/public). Use an explicit directory as-is; only append the folder name for package-derived entries.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Update to pnpm 11.5.2 and cs3d 5.0.2

* Lock file

* fix: Update to newer versions of actions to try to fix hang

* Remove unnecessary version

* fix: Tests that are flaky

* PR comments

* Incorrect run name

* docs: Explain pluginConfig tooling

* Updated notes on pluginConfig and PR comments

* fix: resolve plugins in rsbuild build and fix directory-based asset copy

rsbuild.config.ts: merge getPluginResolveAliases() and an @ohif/app$ alias into resolve.alias, and add resolve.modules (root, platform/app, platform/ui node_modules) so extensions resolve their shared @ohif/* imports. Brings the rsbuild (dev:fast) path to parity with webpack.pwa.js / webpack.base.js.

writePluginImportsFile.js: treat a 'directory' on an extension/mode entry as the package root and copy its public/ and dist/ subdirs instead of the whole directory; public-section entries keep copying their directory verbatim via a new literalDirectory flag.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: share resolve alias/modules between webpack and rsbuild configs

Extract the resolve.alias (@ohif/app, @, @components, ...) and the node_modules search paths into .webpack/resolveConfig.js, the single source of truth consumed by both webpack.base.js (and every per-package webpack.prod/.dev.js that merges it) and rsbuild.config.ts. getModules(srcDir) appends the building package's own source root, preserving the previous per-package behavior. Ends the drift where the rsbuild path kept missing aliases/module paths that webpack.base.js already had.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Add a timeout on git fetch and avoid all the unnecessary mirrros

* PR comments and tests

* Remove cache to prevent corrupting the cache key/setup.

* Fix stale/corrupted pnpm installer

---------

Co-authored-by: Alireza <ar.sedghi@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bill WallaceClaude Opus 4.8Alireza
 authored and GitHub committed 2026-06-12 16:04:56 -04:00
1 parent 571c2b4ff0
commit f1cc2ee13a
126 files changed
+31623 -55381
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

platform/docs/bun.lockb
BIN
View File
Binary file not shown.
platform/docs/docs/migration-guide/3p12-to-3p13/build-tooling.md
+403
View File
@@ -0,0 +1,403 @@
---
sidebar_position: 4
sidebar_label: Build Tooling (Rspack)
title: Webpack to Rspack v2
summary: 3.13 swaps Webpack for Rspack v2 across the monorepo. This guide covers the new build commands, plugin replacements, and how to update custom extensions that ship their own webpack config.
---
# Webpack to Rspack v2
OHIF 3.13 replaces Webpack with [Rspack](https://rspack.dev) v2 as the
default bundler for the app, every extension, every mode, and the
`@ohif/ui-next` / `@ohif/ui` / `@ohif/i18n` / `@ohif/core` packages.
:::caution The `.webpack/` files are now Rspack configs
The directory layout and filenames are unchanged — you will still find
`.webpack/webpack.base.js`, `.webpack/webpack.pwa.js`, and a
`.webpack/webpack.prod.js` in each package. **Despite the `webpack` name,
these files now configure Rspack.** They `require('@rspack/core')` (aliased
to a local `webpack` variable so the rest of the config reads the same) and
are run by the `rspack` CLI. The names were kept to minimize churn and keep
custom-extension forks merging cleanly — do not assume a file called
`webpack.*.js` runs Webpack.
:::
There is no Webpack fallback. Webpack and all of its plugins have been
removed from the dependency tree; the only supported bundler is Rspack
(plus Rsbuild for the `dev:fast` path, see below).
## Why Rspack
Rspack is API-compatible with most of the Webpack v5 plugin ecosystem
but written in Rust. For the OHIF tree the practical wins are:
- 3-5x faster cold builds and `--watch` rebuilds.
- Built-in SWC minification (no separate `terser-webpack-plugin`).
- First-party drop-in replacements for the plugins that previously
ate the bulk of build time (`MiniCssExtractPlugin`, `CopyWebpackPlugin`,
`HtmlWebpackPlugin`).
## New scripts
`platform/app/package.json` was rewritten to invoke `rspack` instead of
`webpack`:
```diff
- "build": "node --max_old_space_size=8096 ./../../node_modules/webpack/bin/webpack.js --progress --config .webpack/webpack.pwa.js",
+ "build": "cross-env NODE_OPTIONS=--max-old-space-size=24576 rspack build --config .webpack/webpack.pwa.js",
- "dev": "cross-env NODE_ENV=development webpack serve --config .webpack/webpack.pwa.js",
+ "dev": "cross-env NODE_ENV=development rspack serve --config .webpack/webpack.pwa.js",
- "dev:orthanc": "… webpack serve --config .webpack/webpack.pwa.js",
+ "dev:orthanc": "… rspack serve --config .webpack/webpack.pwa.js"
```
Notes:
- The build now requests `--max-old-space-size=24576` (24 GB) via
`NODE_OPTIONS`. The previous 8 GB limit is no longer enough for full
prod builds.
- `webpack serve` is replaced by `rspack serve`. All `dev:*` variants
(`dev:orthanc`, `dev:dcm4chee`, `dev:static`, …) were updated the same way.
- `dev:no:cache` no longer passes `--no-cache` (Rspack's CLI does not
expose it). It is now identical to `dev`; production caching is disabled
unconditionally in the config instead (see "Caching" below).
- `dev:fast` runs **Rsbuild** rather than Rspack directly
(`rsbuild dev --config ../../rsbuild.config.ts`). Rsbuild is the
higher-level toolchain built on Rspack; it is used only for the fast
dev-server path and is configured separately in `rsbuild.config.ts`.
## Dependency changes
`platform/app/package.json` (and every other workspace package that ships a
`.webpack/webpack.prod.js`) **adds**:
```json
{
"devDependencies": {
"@rspack/cli": "^2.0.0",
"@rspack/core": "^2.0.0",
"@rspack/dev-server": "^2.0.0",
"@rspack/plugin-react-refresh": "^2.0.0"
}
}
```
and **removes** the Webpack toolchain that is no longer used:
```diff
- "webpack": "5.105.0",
- "@pmmmwh/react-refresh-webpack-plugin": "0.5.17",
- "clean-webpack-plugin": "4.0.0",
- "copy-webpack-plugin": "10.2.4",
- "html-webpack-plugin": "5.6.3",
- "terser-webpack-plugin": "5.3.14",
- "webpack-dev-server": "5.2.2",
- "workbox-webpack-plugin": "6.6.1",
- "dotenv-webpack": "1.8.0",
- "extract-css-chunks-webpack-plugin": "4.10.0",
```
(`webpack-merge` is kept — Rspack configs still use it to merge the base
and per-package configs.)
The root `rsbuild.config.ts` path additionally depends on `@rsbuild/core`,
`@rsbuild/plugin-react`, and `@rsbuild/plugin-node-polyfill`.
## Shared base config (`.webpack/webpack.base.js`)
`webpack.base.js` is the file most consumers extend in their own
extensions. It now requires `@rspack/core` instead of `webpack`:
```diff
- const webpack = require('webpack');
+ const webpack = require('@rspack/core');
```
Rspack exports the same `DefinePlugin`, `ProvidePlugin`, and
`IgnorePlugin` constructors under the same names, so most plugin code
is unchanged — which is why the local variable is still called `webpack`.
### Plugin replacements
| 3.12 (Webpack) | 3.13 (Rspack) |
|-----------------------------------------|---------------------------------------------------------------|
| `mini-css-extract-plugin` | `require('@rspack/core').CssExtractRspackPlugin` |
| `clean-webpack-plugin` | `output: { clean: true }` |
| `copy-webpack-plugin` | `require('@rspack/core').CopyRspackPlugin` |
| `html-webpack-plugin` | `require('@rspack/core').HtmlRspackPlugin` |
| `@pmmmwh/react-refresh-webpack-plugin` | `require('@rspack/plugin-react-refresh')` |
| `terser-webpack-plugin` | Built-in `SwcJsMinimizerRspackPlugin` (no config needed) |
| `workbox-webpack-plugin` (`InjectManifest`) | Custom `InjectServiceWorkerManifestPlugin` in `webpack.pwa.js` |
| `dotenv-webpack` | Plain `require('dotenv').config()` |
`InjectServiceWorkerManifestPlugin` is a small inline plugin that
re-implements what `workbox-webpack-plugin`'s `InjectManifest` did, but
on top of Rspack's compilation hooks (`thisCompilation` →
`processAssets`, emitting a `RawSource`). It is defined locally in
`platform/app/.webpack/webpack.pwa.js` — copy it into your own
`webpack.pwa.js` derivative if you forked that file.
The React Refresh plugin is loaded defensively (`try/require`) and is
skipped when it is unavailable, in production, or during e2e coverage
runs (`COVERAGE=true`), since the refresh runtime's overlay iframe
interferes with Playwright/Cypress pointer events.
### Library output
Every package-level `webpack.prod.js` switched from the legacy library
flags to the structured `output.library` form:
```diff
output: {
- library: 'ohif-extension-cornerstone',
- libraryTarget: 'umd',
+ library: {
+ name: 'ohif-extension-cornerstone',
+ type: 'umd',
+ },
path: ROOT_DIR,
filename: pkg.main
}
```
If your extension uses the old flat `library` / `libraryTarget` keys,
move to the nested form — Rspack is stricter about validating this shape.
### Minifier
Terser is gone. Production builds use Rspack's built-in SWC minifier
unconditionally:
```diff
if (isProdBuild) {
- config.optimization.minimizer = [
- new TerserJSPlugin({ parallel: true, terserOptions: {} }),
- ];
+ config.optimization.minimizer = [new webpack.SwcJsMinimizerRspackPlugin()];
}
```
No options are needed for the common case. If you previously tuned
`terserOptions`, port the equivalent settings to the SWC minimizer's
options object.
### Source maps
The devtool setting is **unchanged** from 3.12 — production builds still
emit full `source-map`, development uses `cheap-module-source-map`, and a
`QUICK_BUILD=true` build disables source maps and minification entirely
(`config.devtool = false`):
```js
devtool: isProdBuild ? 'source-map' : 'cheap-module-source-map',
// …
if (isQuickBuild) {
config.optimization.minimize = false;
config.devtool = false;
}
```
### Caching
```diff
- cache: {
- type: 'filesystem',
- },
+ cache: isProdBuild ? false : { type: 'filesystem' },
```
Production builds always run from a clean cache. The development
filesystem cache is unchanged, but the cache directory is no longer
shared with Webpack — clear `.cache/` after upgrading if you see stale
output.
### `IgnorePlugin` for native modules
A new `IgnorePlugin` entry was added to skip Node-only modules pulled
in by the Cornerstone codecs:
```js
new webpack.IgnorePlugin({
resourceRegExp: /^(fs|path)$/,
contextRegExp: /@cornerstonejs[\\/]codec-/,
}),
```
If you removed this when forking `webpack.base.js`, add it back —
without it the prod bundle will try to require `fs` at runtime.
### Node globals (`__filename` / `__dirname`)
A new top-level `node` block tells the bundler to **leave `__filename` and
`__dirname` references un-substituted** rather than mocking them:
```js
node: {
__filename: false,
__dirname: false,
},
```
The Emscripten-compiled Cornerstone codecs reference `__dirname` inside
`if (ENVIRONMENT_IS_NODE)` branches that never run in the browser. Rspack's
default (a `'mock'` value) emits a warning for each such reference; setting
the values to `false` leaves them alone, which is harmless at runtime and
silences the warnings. The same `node` block is mirrored in
`rsbuild.config.ts` for the `dev:fast` path (Rsbuild's default is
`warn-mock`, with the same noisy behavior).
### Workspace package transpile
`.webpack/rules/transpileJavaScript.js` no longer treats `@ohif/*`
packages as opaque `node_modules`:
```diff
mode === 'production'
? excludeNodeModulesExcept([
+ // Workspace packages (needed for pnpm shamefully-hoist where they
+ // resolve through node_modules)
+ '@ohif',
'react-dnd',
'dnd-core',
```
pnpm symlinks workspace packages through `node_modules`, so the
transpile rule has to opt them back in or the production bundle would
ship un-transpiled TypeScript. Custom monorepos that vendor extensions
under a different scope should add their own scope here.
### Module resolution for pnpm
Two resolution changes were needed for pnpm's isolated (non-hoisted)
`node_modules` layout. Both live in `resolve` in `webpack.base.js` (and
`webpack.pwa.js`):
- `resolve.modules` now **leads with a bare `'node_modules'`** before the
absolute paths. This preserves the default importer-relative walk-up so
transitive deps (e.g. `react-remove-scroll` → `tslib`) resolve to the
sibling copy inside `.pnpm/<pkg>/node_modules` rather than an older
hoisted one.
```diff
modules: [
+ 'node_modules',
path.resolve(__dirname, '../node_modules'),
path.resolve(__dirname, '../../../node_modules'),
// …
],
```
- A new `'@ohif/app$'` alias maps the bare specifier to the app source.
A couple of extensions import app-level utilities from `@ohif/app`;
pnpm's isolated layout does not expose the top-level app package to
them, and adding it as a workspace dependency would create an
`app ↔ default` cycle, so the alias resolves it directly (the `$`
makes it an exact match, so deep subpath imports still resolve normally):
```js
'@ohif/app$': path.resolve(__dirname, '../platform/app/src/index.js'),
```
### Plugin resolution from source (`writePluginImportsFile.js`)
Under yarn the app depended on every extension/mode and copied their
`public/` and `dist/` assets out of `node_modules`. Under pnpm + Rspack,
extensions and modes are **not** dependencies of `platform/app`; instead
`writePluginImportsFile.js` resolves the source directory of each plugin
**declared in `pluginConfig.json`**. It scans the `extensions/` and `modes/`
workspaces only to map the *declared* package names to their directories —
packages present in those workspaces but not listed in `pluginConfig.json`
are ignored. The resulting map is exposed two ways:
- `getPluginResolveAliases()` returns a `resolve.alias` map (one exact-match
`"<pkg>$"` entry per plugin in `pluginConfig.json`) that `webpack.pwa.js`
merges into `resolve.alias`, so the generated `pluginImports.js`
`import()`s link to the plugin source without the plugin being a
dependency.
- `createCopyPluginToDist(...)` copies each plugin's `public/` and `dist/`
assets from that same source directory (falling back to `node_modules`
for third-party entries such as `dicom-microscopy-viewer`).
A plugin can be included three ways, all declared as an entry in
`pluginConfig.json`:
1. **In-tree workspace** — a package under `extensions/` or `modes/`. Declare
it by `packageName`; its source directory is found by the workspace scan.
2. **External, out-of-tree source** — a checkout that lives outside this repo
(e.g. an extension generated by the OHIF CLI). Add a `directory` field to
the entry. The path may be absolute, `~`-relative to the home directory, or
`.`-relative to the repo root; `workspacePluginDir()` uses it directly and
skips the workspace scan.
3. **Installed dependency** — add the package to the **root `package.json`** as
a normal dependency and declare it by `packageName` (no `directory`). It then
resolves from `node_modules` like any other installed package: the bare
specifier flows through webpack's normal module walk-up (no alias is
generated), and `pluginAssetDir()` copies its `public/`/`dist/` assets from
`node_modules`. This is the path used for third-party packages such as
`dicom-microscopy-viewer`.
If you maintain a fork that injects extensions a different way, this is the
seam to update.
## Per-package webpack.prod.js
For every workspace package that previously had a `webpack.prod.js`,
update the top of the file:
```diff
- const webpack = require('webpack');
+ const webpack = require('@rspack/core');
const { merge } = require('webpack-merge');
- const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+ const MiniCssExtractPlugin = webpack.CssExtractRspackPlugin;
```
and replace the flat library options with the nested form shown above.
The rest of the file (`merge(...)`, `entry`, `externals`, `output.path`,
`output.filename`) is unchanged.
## Custom extensions
If you maintain an out-of-tree OHIF extension that uses the OHIF
template, do the following:
1. Add `@rspack/cli`, `@rspack/core`, `@rspack/dev-server`, and
`@rspack/plugin-react-refresh` to `devDependencies` (`^2.0.0`), and
remove `webpack`, `webpack-dev-server`, and the webpack-specific plugins
(`mini-css-extract-plugin`, `copy-webpack-plugin`, `html-webpack-plugin`,
`clean-webpack-plugin`, `terser-webpack-plugin`,
`@pmmmwh/react-refresh-webpack-plugin`, `workbox-webpack-plugin`,
`dotenv-webpack`).
2. Replace `require('webpack')` with `require('@rspack/core')` in your
`.webpack/*.js` files (you can keep the local variable named `webpack`).
3. Update plugin imports as shown in the table above, and switch the flat
`library`/`libraryTarget` keys to the nested `output.library` form.
4. Change your build script from `webpack` to `rspack build` (and
`webpack serve` to `rspack serve`).
5. If you re-export the OHIF base config, re-pull it after upgrading —
the `IgnorePlugin`, `node` block, `transpileJavaScript`, and pnpm
resolution changes only land when you re-merge.
## Known migration notes
- **`@million/lint`** integration is removed from `webpack.pwa.js`
(it was already commented out in 3.12).
- **`Dotenv` plugin** is replaced by a top-level `dotenv.config()`
call. If you relied on the plugin's `safe: true` behavior, move
that check into your config loader.
- **Dev server proxy** moved from the object-keyed shape to the
array-of-`{ context, target }` shape that `@rspack/dev-server`
expects:
```diff
- proxy: [{ '/dicomweb': 'http://localhost:5000' }],
+ proxy: [{ context: ['/dicomweb'], target: 'http://localhost:5000' }],
```
- **Dev-server overlay** is disabled when `COVERAGE=true` (the overlay
iframe intercepts pointer events and breaks Playwright/Cypress clicks);
it is kept on for normal local dev.
- The `dev:no:cache` script is now identical to `dev` — keep it as an
alias if external scripts call it, or delete it.
</content>
</invoke>
platform/docs/docs/migration-guide/3p12-to-3p13/index.md
+13
View File
@@ -12,4 +12,17 @@ import { useCurrentSidebarCategory } from '@docusaurus/theme-common';
This guide covers changes when upgrading from OHIF version 3.12 to version 3.13.
The largest changes in 3.13 are infrastructure-level:
- **[Package Manager](./package-manager.md)** — the monorepo moves from
yarn + lerna to **pnpm workspaces**, with new install/run commands
and a `workspace:*` syntax for cross-package dependencies.
- **[Build Tooling](./build-tooling.md)** — Webpack is replaced with
**Rspack v2** across the app and every extension/mode, with new
plugin imports and faster build commands.
- **[Node Version](./node-version.md)** — the minimum Node.js runtime
is now **24**.
- **[SegmentationService](./segmentation-service.md)** — the
`removeSegmentationRepresentations` method was renamed.
<DocCardList items={useCurrentSidebarCategory().items.filter(item => item.docId !== 'migration-guide/3p12-to-3p13/index')} />
platform/docs/docs/migration-guide/3p12-to-3p13/node-version.md
+119
View File
@@ -0,0 +1,119 @@
---
sidebar_position: 5
sidebar_label: Node Version
title: Node.js 24 Requirement
summary: 3.13 raises the minimum Node.js version from 18 to 24. This guide covers the affected engines fields, CI runners, and how the bump interacts with the pnpm and Rspack upgrades.
---
# Node.js 24
OHIF 3.13 bumps the minimum supported Node.js runtime from 18 to **24**.
The `.node-version` file at the repository root and every workspace
package's `engines.node` field have been updated.
```diff
- .node-version 20.9.0
+ .node-version 24
```
```diff
"engines": {
- "node": ">=18",
- "npm": ">=6",
- "yarn": ">=1.20.0"
+ "node": ">=24",
+ "pnpm": "11.1.1"
}
```
The `npm` and `yarn` engines fields are removed because the repository
no longer supports either as the install path — see the
[Package Manager guide](./package-manager.md).
## Why Node 24
- Rspack v2 requires a modern V8 build (Node 24 ships V8 12.x), which
is needed for the SWC-based minifier to work without falling back to
Babel transforms.
- pnpm 11's `shamefullyHoist` + workspace symlink layout depends on
Node 20.10+ `fs.symlink` semantics; Node 24 is the current LTS line
and is what CI is pinned to.
- The Cornerstone3D codecs use top-level `await` and the modern
`Uint8Array`/`Buffer` interop introduced in Node 22+.
- The 24 GB `--max-old-space-size` setting in the prod build script
benefits from Node 24's improved large-heap GC.
## Affected files
Updated in this release:
- `.node-version` — pinned to `24`.
- `package.json` (root) — `engines.node >=24`, `engines.pnpm 11.1.1`.
- Every workspace package's `engines.node` field, including
`platform/app`, `platform/core`, `platform/ui`, `platform/ui-next`,
`platform/i18n`, `platform/cli`, every `extensions/*` package, and
every `modes/*` package.
- `platform/cli/templates/extension/dependencies.json` and
`platform/cli/templates/mode/dependencies.json` — extensions and
modes generated from the CLI now require Node 24 and pnpm 11.1.1.
- CI config (`.github/workflows/*`, `.circleci/config.yml`,
`.netlify/build-deploy-preview.sh`) was bumped in lockstep.
## Local environments
If you use a Node version manager:
```bash
# nvm
nvm install 24
nvm use 24
# fnm
fnm install 24
fnm use 24
# volta
volta install node@24
```
`.node-version` is honored by `fnm`, `nodenv`, `asdf`, and (with the
`engines-strict` setting) `pnpm`. Most editors with a Node toolbar
will switch automatically when you cd into the repo.
## CI runners
Update your pipeline images:
```diff
- node-version: '20.9.0'
+ node-version: '24'
```
GitHub Actions: `actions/setup-node@v4` with `node-version: '24'`.
CircleCI: `cimg/node:24.0` (or newer).
Docker base image: `node:24-alpine` for production builds. The
project's `Dockerfile` was updated to match.
## Behavior changes worth knowing
- **`punycode`**: Node 24 prints a deprecation warning when the
built-in `punycode` is required. Some transitive dependencies still
do this; the warning is harmless but noisy. Set
`NODE_OPTIONS=--no-deprecation` if you need to silence it in CI.
- **OpenSSL provider**: Node 24 uses OpenSSL 3.x. If you previously
set `NODE_OPTIONS=--openssl-legacy-provider` for old Webpack hashes,
remove it — Rspack does not need it.
- **`fetch` is global**: Node 24 has the WHATWG `fetch` built in.
Polyfills like `node-fetch` are no longer needed in scripts that
run under Node.
- **ESM resolution is stricter**: relative imports in `.js` files
inside `"type": "module"` packages must include the file extension.
This mainly affects test helpers under `tests/utils/`.
## Compatibility window
If you cannot move to Node 24 yet, the `build:webpack` fallback in
`platform/app/package.json` runs under Node 22, but production
support is not guaranteed and the Rspack scripts will refuse to run.
We recommend planning the runtime upgrade alongside the 3.13
deployment.
platform/docs/docs/migration-guide/3p12-to-3p13/package-manager.md
+190
View File
@@ -0,0 +1,190 @@
---
sidebar_position: 3
sidebar_label: Package Manager (pnpm)
title: Yarn / Lerna to pnpm
summary: 3.13 moves the monorepo from yarn + lerna to pnpm workspaces. This guide covers the new install/run commands, workspace dependency syntax, and changes to CLI-generated extensions and modes.
---
# Yarn + Lerna to pnpm
OHIF 3.13 replaces the `yarn` + `lerna` toolchain with **pnpm workspaces**.
The repository now uses a single `pnpm-lock.yaml` and a `pnpm-workspace.yaml`
manifest at the root. `yarn.lock`, `lerna.json`, `nx.json`, `bun.lock`,
the `addOns/` directory, and `preinstall.js` have all been removed.
## Required tools
| Tool | Old minimum | New minimum |
|------|---------------|-------------|
| node | `>=18` | `>=24` |
| pnpm | _(unused)_ | `>=11` |
| yarn | `>=1.20.0` | _(removed)_ |
| npm | `>=6` | _(removed)_ |
The root `package.json` declares `"packageManager": "pnpm@11.1.1"`. If you use
[Corepack](https://nodejs.org/api/corepack.html), running any pnpm command in
the repo will pick the correct version automatically:
```bash
corepack enable
corepack prepare pnpm@11.1.1 --activate
```
## Install and run commands
Replace your existing yarn and lerna commands with their pnpm equivalents.
| 3.12 (yarn / lerna) | 3.13 (pnpm) |
|-------------------------------------------|---------------------------------------------|
| `yarn install --frozen-lockfile` | `pnpm install --frozen-lockfile` |
| `yarn install` | `pnpm install` |
| `yarn run dev` | `pnpm run dev` |
| `yarn run build` | `pnpm run build` |
| `yarn run test:unit` | `pnpm run test:unit` |
| `lerna run build --stream` | `pnpm -r run build` |
| `lerna run dev:viewer --stream` | `pnpm --filter @ohif/app run dev:viewer` |
| `lerna run clean --stream` | `pnpm -r run clean` |
The root `scripts` section was rewritten to use `pnpm --filter @ohif/app run …`
for app-targeted scripts and `pnpm -r run …` for monorepo-wide scripts.
There is no `preinstall` script anymore.
## `.npmrc`
A new `.npmrc` at the repository root controls install behavior:
```ini
frozen-lockfile=true
```
CI installs error out if the lockfile would change. To update the lockfile
locally, use `pnpm install --no-frozen-lockfile` (also exposed as the
`install:update-lockfile` script).
## `pnpm-workspace.yaml`
Workspace membership moved out of `package.json` into a dedicated file:
```yaml
packages:
- platform/*
- extensions/*
- modes/*
shamefullyHoist: true
allowBuilds:
'@scarf/scarf': true
'@swc/core': true
core-js: true
core-js-pure: true
cypress: true
protobufjs: true
sharp: true
overrides:
# pinned versions previously declared in package.json resolutions …
```
Two settings worth highlighting:
- **`shamefullyHoist: true`** keeps the install layout flat, the way yarn
v1 produced it. This is required because some OHIF dependencies expect
to resolve transitive packages directly from `node_modules`.
- **`allowBuilds`** is pnpm's allow-list for packages whose install scripts
are allowed to run. If you add a dependency that ships a postinstall
script (native bindings, optimized binaries, etc.) you must add it here
or pnpm will skip the build.
The `addOns/externals/*` workspace entry from 3.12 is **removed**. The
`dicom-microscopy-viewer` and externals devDependencies are now installed
directly through `pnpm-workspace.yaml` overrides — no separate add-on
install step is needed.
## Workspace dependency syntax
Intra-workspace dependencies now use the `workspace:*` protocol instead of
hard-pinned version strings:
```diff
"dependencies": {
- "@ohif/core": "3.13.0-beta.72",
- "@ohif/extension-cornerstone": "3.13.0-beta.72",
- "@ohif/ui-next": "3.13.0-beta.72"
+ "@ohif/core": "workspace:*",
+ "@ohif/extension-cornerstone": "workspace:*",
+ "@ohif/ui-next": "workspace:*"
}
```
When pnpm publishes a workspace package, `workspace:*` is rewritten to the
actual version on disk, so downstream consumers continue to see normal
semver ranges in published `package.json` files.
If you keep an OHIF fork with extra extensions in `extensions/`, you do
**not** need to add them to `pnpm-workspace.yaml` — the glob pattern
already covers them. Inside your extension's `package.json`, change any
`@ohif/*` deps from hard versions to `workspace:*`.
## CLI changes
`platform/cli` (`@ohif/cli`) no longer wraps yarn:
- `getYarnInfo` and `uninstallNPMPackage` now shell out via `execa` to
`npm` / `pnpm` directly rather than depending on the deprecated
`yarn-programmatic` package.
- The CLI invokes scripts with `pnpm run …` and instructs new extension
authors to use pnpm.
- The yarn dependency was removed from `platform/cli/package.json`.
If you previously ran extension/mode commands as `yarn run cli …`,
switch to `pnpm run cli …`.
## CLI extension and mode templates
The `extension` and `mode` templates in `platform/cli/templates/*/dependencies.json`
were updated:
```diff
"engines": {
- "node": ">=14",
- "npm": ">=6",
- "yarn": ">=1.18.0"
+ "node": ">=24",
+ "pnpm": "11.1.1"
},
"scripts": {
"dev": "cross-env NODE_ENV=development webpack --config .webpack/webpack.dev.js --watch --output-pathinfo",
- "dev:my-extension": "yarn run dev",
+ "dev:my-extension": "pnpm rundev",
"build": "cross-env NODE_ENV=production webpack --config .webpack/webpack.prod.js",
- "build:package": "yarn run build",
- "start": "yarn run dev"
+ "build:package": "pnpm runbuild",
+ "start": "pnpm rundev"
}
```
> **Heads up**: the template's `pnpm rundev` / `pnpm runbuild` strings are
> missing the space between `run` and the script name. If you generate a
> new extension from the CLI, replace those with `pnpm run dev` and
> `pnpm run build`.
## Audit and lockfile maintenance
- `yarn audit` and the `bun audit` ignore list have been replaced with a
plain `pnpm audit` in the root script.
- `yarn dlx`-style ad-hoc commands should use `pnpm dlx` instead.
- Update CI cache keys: cache `~/.local/share/pnpm/store` (or the path
reported by `pnpm store path`) keyed on `pnpm-lock.yaml`. Yarn cache
paths are no longer populated.
## Quick migration checklist
1. Install Node 24 and pnpm 11 (or use Corepack).
2. Delete `node_modules` and any `yarn.lock`/`addOns/yarn.lock` from your
fork.
3. Replace hard-pinned `@ohif/*` deps with `workspace:*` in your
workspace packages.
4. Update CI scripts to call `pnpm install --frozen-lockfile` and
`pnpm run …`.
5. Update your cache key to `pnpm-lock.yaml`.
6. Regenerate any extensions you created from the CLI templates and fix
the `pnpm rundev` / `pnpm runbuild` script names.
platform/docs/docs/platform/extensions/index.md
+10 -3
View File
@@ -177,11 +177,18 @@ the top level [`extensions/`][ext-source] directory.
}
```
:::note Important
You SHOULD NOT directly register extensions in the `pluginConfig.json` file.
Use the provided `cli` to add/remove/install/uninstall extensions. Read more [here](../../development/ohif-cli.md)
:::note
You can register extensions by editing the `pluginConfig.json` file directly.
The provided `cli` can also add/remove/install/uninstall extensions
([read more](../../development/ohif-cli.md)), but it is being phased out in
favour of generating extensions with an agent.
:::
For the full set of fields (`packageName`, `version`, `default`, `directory`,
the `public` section) and the three ways a plugin can be located (in-tree,
out-of-tree `directory`, or installed dependency), see the
[pluginConfig.json reference](./pluginConfig.md).
The final registration and import of the extensions happen inside a non-tracked file `pluginImport.js` (this file is also for internal use only).
After an extension gets registered within the `viewer`,
platform/docs/docs/platform/extensions/pluginConfig.md
+132
View File
@@ -0,0 +1,132 @@
---
sidebar_position: 6
sidebar_label: pluginConfig.json
title: pluginConfig.json Reference
summary: Reference for platform/app/pluginConfig.json — the extensions, modes, and public arrays, every entry field (packageName, version, default, directory, and the public-entry import fields), and the three ways a plugin can be located (in-tree workspace, out-of-tree directory, or installed dependency).
---
# pluginConfig.json Reference
`platform/app/pluginConfig.json` declares which extensions, modes, and
third-party public assets are compiled into the viewer build. The build step
([`writePluginImportsFile.js`](https://github.com/OHIF/Viewers/blob/master/platform/app/.webpack/writePluginImportsFile.js))
reads it, resolves each entry to a source directory, generates the (untracked)
`pluginImports.js`, and copies each plugin's static assets into `dist`.
:::note
You can edit `pluginConfig.json` directly to add, remove, or configure plugins
using the fields documented below. The [OHIF CLI](../../development/ohif-cli.md)
can also manage entries, but it is being phased out in favour of generating
extensions and modes with an agent.
:::
## Top-level shape
```jsonc title="platform/app/pluginConfig.json"
{
"extensions": [ /* extension entries */ ],
"modes": [ /* mode entries */ ],
"public": [ /* third-party public-asset entries */ ]
}
```
| Key | Required | Description |
| --- | --- | --- |
| `extensions` | yes | Extensions to make available to the build. |
| `modes` | yes | Modes (workflows) to make available to the build. |
| `public` | no | Third-party packages whose prebuilt assets are copied/loaded at runtime (e.g. `dicom-microscopy-viewer`). Not registered as extensions or modes. |
## Extension / mode entry fields
An entry may be a bare string (the package name) or an object. The object form
supports the following fields:
| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `packageName` | string | — | The package's real name (matches its `package.json` `name`). Required unless `directory` alone identifies the plugin. |
| `version` | string | — | Informational / used by the CLI for install bookkeeping. It does **not** affect build resolution. |
| `default` | boolean | `true` | When `false`, the plugin is **not** added to the auto-registered set loaded at startup (`defaultExtensions` / `defaultModes`). It is still resolvable and can be loaded on demand — e.g. when a registered mode declares it as a required extension. |
| `directory` | string | — | An explicit source directory for an out-of-tree plugin. See [Plugin locations](#plugin-locations). |
```jsonc
{
"extensions": [
// bare string form
"@ohif/extension-default",
// object form, registered by default
{ "packageName": "@ohif/extension-cornerstone", "version": "3.0.0" },
// present in the build but NOT auto-registered; loaded only when a
// registered mode requires it
{
"packageName": "@ohif/extension-cornerstone-dicom-seg",
"version": "3.0.0",
"default": false
}
],
"modes": [
{ "packageName": "@ohif/mode-longitudinal" }
]
}
```
## `public` entry fields
`public` entries are not extensions or modes — they describe third-party assets
that are copied into `dist` and (optionally) imported at runtime via a global.
| Field | Type | Description |
| --- | --- | --- |
| `packageName` | string | Package name, used to resolve the asset directory from `node_modules` when `directory` is not given. |
| `directory` | string | Source directory of the assets to copy. Resolved like the extension `directory` field (absolute, `~`-relative, or `.`-relative to the repo root). |
| `importPath` | string | Path/URL the runtime loader `import()`s. Absolute (`http…` or `/…`) paths are used as-is; otherwise it is prefixed with `PUBLIC_URL`. |
| `globalName` | string | If set, after importing `importPath` the loader returns `window[globalName]` (for UMD/global bundles). |
| `importName` | string | Named export to return from the imported module. Defaults to `default`. Ignored when `globalName` is set. |
| `to` | string | Destination subpath under `dist` for the copied assets. |
```jsonc
{
"public": [
{ "directory": "./platform/public" },
{
"packageName": "dicom-microscopy-viewer",
"importPath": "dicom-microscopy-viewer/dicomMicroscopyViewer.min.js",
"globalName": "dicomMicroscopyViewer",
"directory": "./node_modules/dicom-microscopy-viewer/dist/dynamic-import",
"to": "/dicom-microscopy-viewer/"
}
]
}
```
## Plugin locations
Under pnpm, extensions and modes are **not** dependencies of `platform/app`.
Every entry in `pluginConfig.json` is located one of three ways — only entries
listed here are compiled in; workspace packages that are not listed are ignored.
1. **In-tree workspace** — a package under `extensions/` or `modes/`. Declare it
by `packageName`; the build scans those workspaces and maps the declared name
to its source directory. This is the common case the CLI sets up.
2. **External, out-of-tree source** — a checkout outside this repo (e.g. an
extension generated by the OHIF CLI). Add a `directory` field. The path may
be absolute, `~`-relative to the home directory, or `.`-relative to the repo
root.
```jsonc
{ "packageName": "@acme/extension-foo", "directory": "~/dev/extension-foo" }
```
3. **Installed dependency** — add the package to the **root `package.json`** as a
normal dependency and declare it by `packageName` (no `directory`). It then
resolves from `node_modules` like any other installed package, and its
`public/` and `dist/` assets are copied from there. This is the path used for
third-party packages such as `dicom-microscopy-viewer`.
```jsonc
{ "packageName": "@acme/extension-foo", "version": "1.2.3" }
```
For the build internals behind these (alias generation, asset copying, the
pnpm + Rspack migration), see the
[build tooling migration guide](../../migration-guide/3p12-to-3p13/build-tooling.md#plugin-resolution-from-source-writepluginimportsfilejs).
platform/docs/docs/platform/modes/index.md
+9 -3
View File
@@ -451,11 +451,17 @@ find the `modes` to register.
}
```
:::note Important
You SHOULD NOT directly register modes in the `pluginConfig.json` file.
Use the provided `cli` to add/remove/install/uninstall modes. Read more [here](../../development/ohif-cli.md)
:::note
You can register modes by editing the `pluginConfig.json` file directly.
The provided `cli` can also add/remove/install/uninstall modes
([read more](../../development/ohif-cli.md)), but it is being phased out in
favour of generating modes with an agent.
:::
For the full set of entry fields and the three ways a plugin can be located
(in-tree, out-of-tree `directory`, or installed dependency), see the
[pluginConfig.json reference](../extensions/pluginConfig.md).
The final registration and import of the modes happen inside a non-tracked file `pluginImport.js` (this file is also for internal use only).
platform/docs/package.json
+14 -23
View File
@@ -5,12 +5,12 @@
"scripts": {
"docusaurus": "docusaurus",
"clean": "shx rm -rf dist",
"clean:deep": "yarn run clean && shx rm -rf node_modules",
"clean:deep": "pnpm run clean && shx rm -rf node_modules",
"start": "docusaurus start --port 8001",
"dev": "docusaurus clear && docusaurus start --port 8001",
"docs": "docusaurus start --port 8001",
"build": "docusaurus build && yarn run prepare-markdown-files && yarn run generate-llms-txt && yarn run generate-llms-full-txt",
"build:docs": "docusaurus build && yarn run prepare-markdown-files && yarn run generate-llms-txt && yarn run generate-llms-full-txt",
"build": "docusaurus build && pnpm run prepare-markdown-files && pnpm run generate-llms-txt && pnpm run generate-llms-full-txt",
"build:docs": "docusaurus build && pnpm run prepare-markdown-files && pnpm run generate-llms-txt && pnpm run generate-llms-full-txt",
"prepare-markdown-files": "node ./scripts/prepare-markdown-files.js",
"generate-llms-txt": "node ./scripts/generate-llms-txt.js",
"generate-llms-full-txt": "node ./scripts/generate-llms-full-txt.js",
@@ -21,18 +21,6 @@
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
"dependencies": {
"@docusaurus/core": "3.7.0",
"@docusaurus/faster": "3.7.0",
@@ -96,13 +84,16 @@
"typescript": "5.5.4",
"url-loader": "4.1.1"
},
"resolutions": {
"qs": "6.14.1",
"lodash": "4.17.23",
"webpack": "5.105.0",
"sharp": "0.34.5",
"serialize-javascript": "7.0.4",
"rollup": "2.80.0",
"svgo": "3.3.3"
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
}
}
platform/docs/yarn.lock
-12736
View File
File diff suppressed because it is too large. Load diff