CLI-era extension → 2026 plugin contract
Standalone extensions and modes generated by the old OHIF CLI
(yarn cli create-extension / create-mode) do not load under the 2026
plugin contract without changes. The mechanical work is done for you by
pnpm create ohif migrate ./path-to-your-plugin --dry-run
create-ohif migrate reads your package, prints a report of every change
it will make (each line tagged [rewrite], [ok], or [flag]), and — when
you re-run it without --dry-run — applies the [rewrite] items. That report
is the migration checklist.
It covers packaging and the build only: migrate doesn't change your source. Update your code for the OHIF version you're moving to with the version migration guides, for example 3.7 → 3.8 through 3.13 → 3.14 for a plugin written for 3.7.
This page is the why behind the report. Each section below names a report
item, quotes the CLI-era template it came from, and explains what the 2026
contract requires and the failure it prevents. Read it when a report line is
not self-explanatory, or when a [flag] item asks you to change something the
tool will not touch automatically.
If your plugin is small, regenerate it with pnpm create ohif (choose
extension or mode) and move your src/ over. You get the current template
verbatim and skip the archaeology. Everything below is the in-place
alternative for plugins too large to re-home by hand.
Why the old output never really worked
Before the item-by-item walkthrough, one finding motivates the whole rewrite.
The CLI-era build config declared the bundle's UMD library name twice
(platform/cli/templates/extension/.webpack/webpack.prod.js, lines 14–23):
output: {
library: {
type: 'umd',
umdNamedDefine: true,
},
path: outputFolder,
filename: outputFile,
library: pkg.name,
chunkFilename: '[name].chunk.js',
globalObject: "typeof self !== 'undefined' ? self : this",
},
An object has one value per key, so the second library: pkg.name (a plain
string) silently overwrites the first library: { type: 'umd', … } object.
Webpack fell back to its default library type, so the CLI-era build never
reliably emitted the UMD bundle its own comments documented. The host loads
plugins as UMD globals; a build that does not dependably produce one cannot be
loaded at runtime. That is the root reason the build config is replaced
wholesale rather than patched.
package.json
main → dist/index.umd.js
Before (platform/cli/templates/extension/dependencies.json): no main
at all — only "module": "src/index.tsx". The build wrote to
dist/umd/<name>/.
The contract build (.rspack/rspack.prod.js) emits a single
dist/index.umd.js, and main must point at it. The nested
dist/umd/<name>/ path is gone. module still points at your source entry so
that directory-mode consumers (a directory entry in pluginConfig.json) can
compile your src/ directly.
files, keywords, publishConfig
Before: the CLI-era manifest had no files, no publishConfig, and only
the keywords: ["ohif-extension"] array.
The contract requires:
{
"keywords": ["ohif-extension"],
"main": "dist/index.umd.js",
"module": "src/index.tsx",
"files": ["dist", "src", "public", "README.md"],
"publishConfig": {
"access": "public",
"main": "dist/index.umd.js",
"module": "dist/index.umd.js"
},
"peerDependencies": {
"@ohif/core": ">=3.14.0-beta.0 <4",
"react": "^19.2.7",
"react-dom": "^19.2.7"
}
}
These are the create-ohif extension template's fields, as written for 3.14
(the template is normative: if this page and the template ever differ,
follow the template). Note what is not here:
- No
publishConfig.typesand noexportsmap. The plugin toolchain does not emit.d.tsfiles, so there is nothing to point atypesfield at, and the host resolves the UMD viamain/module, not anexportsmap. Adding either would advertise a file no build step produces. filesshipssrcas well asdistbecause directory-mode consumers compile from source.keywordscarriesohif-extension(orohif-modefor a mode) — registry discovery andpnpm plugin doctorkey off it. Migrate also reads it to tell an extension from a mode, aspnpm run plugin adddoes. The CLI templates wrote it, but if yours has neither keyword, migrate stops and asks you to add one. Inside a checkout it goes by the folder instead (extensions/ormodes/), and flags a keyword that disagrees with the folder.- No
repository. The CLI template set it to"OHIF/Viewers", so npm linked every generated package to OHIF's repo; migrate drops that value. Add your ownrepositoryif you want npm to link to your source.
publishConfig rewrites only main/module at publish time so the published
tarball points consumers at the built UMD while the working tree keeps pointing
at source. This rewrite only happens under pnpm publish — the npm CLI
ignores publishConfig field overrides, so publish with pnpm.
engines
Older CLI-era packages declare "engines": { "node": ">=14", "npm": ">=6", "yarn": ">=1.x" }.
migrate sets engines.node to the template's value (>=24 for 3.14),
unless you already require a higher Node, and drops the npm and yarn
entries because the package uses pnpm now. Other entries are left alone.
peerDependencies
Before (dependencies.json, lines 16–28): the CLI-era peer set wrongly
included the bundler itself —
"peerDependencies": {
"@ohif/core": "^{LATEST_OHIF_VERSION}",
"@ohif/extension-default": "^{LATEST_OHIF_VERSION}",
"@ohif/extension-cornerstone": "^{LATEST_OHIF_VERSION}",
"@ohif/i18n": "^1.0.0",
"prop-types": "^15.6.2",
"react": "^18.3.1",
"react-dom": "^18.3.1",
"react-i18next": "^12.2.2",
"react-router": "^6.23.1",
"react-router-dom": "^6.23.1",
"webpack": "5.89.0",
"webpack-merge": "^5.7.3"
}
The contract:
- Build tooling is never a peer.
webpack/webpack-mergeare dropped; the.rspacktoolchain lives indevDependencies. A consumer installing your plugin should not be asked to satisfy a bundler. @ohif/*peers use the host range,>=<major>.<minor>.0-beta.0 <<major+1>taken from thecreate-ohifversion (for 3.14,>=3.14.0-beta.0 <4). Starting atbeta.0keeps the range open to a viewer on an earlier beta thancreate-ohif.pnpm run plugin doctorchecks the@ohif/corepeer against the viewer's version; the runtime loader checks a descriptor'scoreVersionRange, not peer ranges.- Shared packages follow the host's major version. The host shares React
and
react-dom19,react-routerandreact-router-dom6,i18next19,react-i18next12,@cornerstonejs/coreand@cornerstonejs/tools5,dcmjs0.52 andgl-matrix3 (create-ohif'shost-shared-majors.json). A peer on another major is set to the host's (^19.0.0,^5.0.0,^0.52.0, …); a range already on it is left alone, and an exact version on it becomes a caret range of itself (19.2.0becomes^19.2.0), since an exact peer is met by that one release only. Any of them underdependenciesmove topeerDependenciesby the same rule, or are dropped if they are already peers: the build leaves them external, so an installed copy is never used. A copy underdevDependencies, for types and tests, is yours: migrate flags it when it is on another major, and flags a moved package that has none, since peers aren't installed. The CLI-era peers above become"react": "^19.0.0"and"react-dom": "^19.0.0"; React Router andreact-i18nextare already on the host's majors and stay. - Other cornerstone packages are flagged.
@cornerstonejs/adapters, the image loader and the rest aren't shared, and your build leaves them out all the same. Compiled into a viewer, they resolve like any other dependency. In a runtime bundle they areundefined: see Sharing more libraries from a fork. Cornerstone releases its packages together, so when migrate moves your@cornerstonejs/coreto another major, it flags each of them still on your old one. @ohifpackages are peers too. An@ohif/*entry underdependenciesmoves topeerDependenciesat the host range, as does aworkspace:*entry underdevDependencies, which can't be installed outside an OHIF checkout. A dev copy at a real version stays.- Inside a checkout, the shared packages stay where you list them. A plugin
directly in a checkout's
extensions/ormodes/keeps each shared package in its section, as the repo's own plugins do. One on another major than the checkout installs is set to the checkout's version, read from the dependencies ofplatform/appand the SDK packages.@ohif/*entries becomeworkspace:*wherever they are. - Check the majors that moved. Aligning a peer to the host can move it to a new major version (React 18 to 19, for example). If your code was written for an older major, check that package's breaking changes; the report ends with a note naming the packages whose versions changed.
- Drop the
@ohif/uipeer if present.@ohif/uiis legacy and the host does not hand it to runtime plugins; port UI to@ohif/ui-next(the APIs differ — this is a[flag], migrate will not rewrite your imports). - Drop the
@ohif/apppeer if present. The host is the app, and the published@ohif/appis the built viewer, not a library, so a peer on it can never supply anything your code imports. - Peers on unpublished OHIF packages are flagged. Only
@ohif/core,@ohif/ui-next,@ohif/i18n,@ohif/extension-defaultand@ohif/extension-cornerstoneare published as libraries (see Published packages). A peer on any other@ohifpackage, such as@ohif/extension-cornerstone-dicom-sr, is kept and rewritten to the host range, because it still resolves in an OHIF checkout. But it can't be installed from npm at this version: only old 3.13.x releases are there, and the range also matches those. As a runtime bundle, an import from such a package needs that extension loaded first (list it inwindow.config.extensions), or anextensionManager.getModuleEntry(…)lookup instead.
scripts
migrate rewrites dev, build and build:package to the .rspack builds.
It also:
- drops
dev:my-extensionanddev:cornerstone, the CLI templates' aliases fordev, while they are unchanged (nothing calls them); - rewrites any remaining
yarn run …call, oryarn <script>, topnpm run …, and flags any other yarn call (for exampleyarn install, or yarn later in a command) for you to translate by hand; - flags scripts that run jest when jest isn't a dependency. New scaffolds use
vitest for tests. Inside a checkout the scripts are left alone: the root
installs jest and runs every plugin's
test:unit:ci, as it does for its own plugins' identical scripts.
pnpm-workspace.yaml and .npmrc
The migration adds autoInstallPeers: false to the package's
pnpm-workspace.yaml (creating the file, with the template's allowBuilds
list, if there is none), and an .npmrc with
auto-install-peers=false for pnpm older than 12, which ignores the setting in
.npmrc. The peers above are provided by the host at runtime; pnpm must not
auto-install its own copies, which would produce duplicate React/@ohif/core
instances.
Inside an OHIF checkout (the plugin directly in its extensions/ or modes/
folder) the opposite applies: the checkout root's files govern, and a nested
pnpm-workspace.yaml makes pnpm treat the plugin folder as its own workspace,
so workspace:* peers stop resolving. There, migrate removes both files
instead, and leaves the plugin the way
create-ohif --in-tree
scaffolds one.
Outside a checkout, migrate treats each package as a repository of its own. If
one repository holds several plugins as a single pnpm workspace, such as a mode
and its extension, migrate still writes a pnpm-workspace.yaml and an .npmrc
into each package. pnpm uses the nearest pnpm-workspace.yaml above the
directory a command runs in, so each package would install as a workspace of
its own. After migrating every package, move the settings to the repository
root and delete the nested files:
- In the root
pnpm-workspace.yaml, next to itspackages:list, setautoInstallPeers: falseand merge in theallowBuildsentries from the nested files. - In the root
.npmrc, setauto-install-peers=false. - Delete each package's
pnpm-workspace.yamland.npmrc, and anypnpm-lock.yamlan install inside a package created.
Build config: .webpack/ → .rspack/
The old .webpack/webpack.prod.js is removed and replaced with the current
template's .rspack/rspack.prod.js plus a vendored .rspack/pluginExternals.js.
Two parts of that config are the contract — the host loads your bundle
against them — and they are the reason a hand-patch is not enough.
output.library
Instead of the doubled-key output above, the contract config declares the UMD library once, correctly:
output: {
path: path.resolve(__dirname, '../dist'),
filename: 'index.umd.js',
library: { name: pkg.name, type: 'umd' },
globalObject: "typeof self !== 'undefined' ? self : this",
clean: true,
},
The UMD global (window[pkg.name]) holds the whole module: the extension
object as default, which the host registers, plus every named export, which
another plugin can import. An extension compiled into the viewer is shared on
window the same way.
externals — the breaking change
This is the single change most likely to break a CLI-era plugin at runtime.
Before (webpack.prod.js, lines 25–46): externals were hand-rolled
per-target objects covering only react, @ohif/core, and @ohif/ui —
externals: [
{
react: {
root: 'React',
commonjs2: 'react',
commonjs: 'react',
amd: 'react',
},
'@ohif/core': {
commonjs2: '@ohif/core',
commonjs: '@ohif/core',
amd: '@ohif/core',
root: '@ohif/core',
},
'@ohif/ui': {
commonjs2: '@ohif/ui',
commonjs: '@ohif/ui',
amd: '@ohif/ui',
root: '@ohif/ui',
},
},
],
Everything not in that list — @cornerstonejs/*, dcmjs, gl-matrix,
react-dom, react/jsx-runtime — was bundled into the plugin. A plugin
that bundles its own React DOM or its own Cornerstone runs a second copy
alongside the host's, which breaks hooks, tool state, and rendering in ways
that surface only at runtime.
The contract externalizes the full host-provided surface:
module.exports = [
/\b(vtk.js)/,
/\b(dcmjs)/,
/\b(gl-matrix)/,
/^@ohif/,
/^@cornerstonejs/,
'react',
'react-dom',
'react/jsx-runtime',
'react-router',
'react-router-dom',
'i18next',
'react-i18next',
];
react, react-dom, react/jsx-runtime, react-router, react-router-dom,
i18next and react-i18next are now host-provided globals.
If your source imported any of the newly-external packages expecting them
bundled, nothing changes in your code — but the runtime now supplies the
host's single copy, which is the point.
migrate also flags imports that only resolve when the plugin is compiled into
an OHIF checkout: the app's own aliases (@, @components, @hooks,
@routes, @state), @ohif/app, and @ohif/ui-next subpaths such as
@ohif/ui-next/lib/utils. They work for a directory link or an in-tree
package. In a runtime bundle the aliases can't be resolved, and @ohif/app and
the subpaths are undefined: the host shares @ohif/ui-next only as a whole,
and doesn't share @ohif/app at all. If you build a runtime bundle, replace
them:
| Instead of | Use |
|---|---|
useAppConfig from @state, to read the app config | extensionManager.appConfig |
history from @ohif/app, to navigate | useNavigate() from react-router-dom |
preserveQueryParameters or preserveQueryStrings from @ohif/app | Your own copy (it's a short function), or URLSearchParams |
An @ohif/ui-next/lib/… or @ohif/ui-next/components/… subpath | The same export from @ohif/ui-next itself |
Anything else under @, @components, @hooks or @routes | What @ohif/core, @ohif/ui-next and the shared extensions export |
The vendored pluginExternals.js is a verbatim copy of the monorepo's
.rspack/pluginExternals.js; create-ohif keeps the two in sync. See
Webpack to Rspack v2 and the 3.14
.rspack and Rsbuild changes for the app-level
side of the same bundler move.
babel / other build files
babel.config.js and the Babel packages (@babel/*, babel-plugin-*,
babel-preset-*) are no longer used — the .rspack build compiles TS/JSX with
builtin:swc-loader. migrate flags them for removal rather than pinning, and
removes eslint-loader with the rest of the webpack tooling. It also flags
eslint, babel-eslint and dotenv for removal when no script, config or
source file uses them (the CLI templates listed them but never ran them).
Inside a checkout, Babel is still in use: jest compiles a plugin's tests with
babel-jest, which reads the plugin's own babel.config.js, and each of the
checkout's plugins has a one-line one that re-exports the root's
(module.exports = require('../../babel.config.js');). So migrate flags a
babel.config.js that doesn't, to be replaced with that line, and flags the
Babel packages under devDependencies for removal because the root install
provides them. @babel/runtime under dependencies stays, as in the
checkout's plugins.
Any other custom build file (webpack.config.js, a vite.*/rollup.* config,
extra files in .webpack/) is flagged, not rewritten: migrate leaves it in
place and you port any custom settings into .rspack/rspack.prod.js by hand.
migrate also removes two kinds of leftover: other package managers' lockfiles,
yarn.lock, package-lock.json, bun.lock and bun.lockb (pnpm writes its
own pnpm-lock.yaml), and the CLI-era build output in
dist/umd/<package name>/, which would otherwise ship in a published package
next to the new dist/index.umd.js. Anything else under dist/umd/ is flagged
and left in place.
The extension object: id and default export
The extension must export default an object whose id equals the
package.json name. The CLI-era template already did both (src/index.tsx
default-exports an object with id sourced from src/id.js), so most ports
only need to verify it — the loader rejects a plugin whose id does not
match its package name. migrate does not rewrite your source object; this is a
verification step.
Registration and discovery
The CLI commands that used to register and find plugins are gone. Their replacements:
yarn cli add-extension <pkg>→pnpm plugin add <pkg>. This writes an explicit entry intoplatform/app/pluginConfig.json. Delete any deadversionfield from an old hand-written entry — the config schema now rejects unknown fields. See Extension installation for the from-npm, from-checkout, and in-tree forms.- Load without a rebuild — declare the plugin as a runtime descriptor in
app-config.jsinstead. See Runtime Extensions; the load is recorded atwindow.__ohif.runtimePluginsfor auditing. yarn cli search→ the extension gallery plusnpm search ohif-extension(the registry keyword query the CLI search ran).
Styles
CLI-era extensions that relied on the host's Tailwind classes must now ship
self-contained CSS. The in-tree host content globs cover pluginConfig
entries, but published and runtime-loaded plugins carry their own CSS through
the build (the .rspack CSS pipeline emits index.css) and, for runtime
descriptors, the descriptor styles: [] field. migrate adds a
tailwind.config.js (with preflight off) for extensions that lack one.
Verify
After the rewrites, build the plugin in its own folder:
pnpm install
pnpm run build
doctor isn't part of the plugin itself; it runs from an OHIF checkout. Link
the plugin there and check it:
pnpm run plugin link ../path/to/your-plugin
pnpm run plugin doctor
doctor checks that the link resolves, that the plugin's @ohif/core range
covers this viewer's version, that the plugin has no copy of its own of React
or another package the viewer provides, and, for a mode, that the extensions it
needs are installed and declared. In a create-ohif workspace, run
pnpm run doctor at the workspace root instead.
Then load the plugin in the viewer and confirm it registers (for a
runtime-loaded plugin, check window.__ohif.runtimePlugins for its audit
record). Run pnpm run plugin unlink <name> when you're done if you don't
want to keep the link. The pnpm run plugin helpers replace the deleted CLI;
see the OHIF CLI removal for the full command
mapping.
Related
- De-forking guide — if your customizations live inside a fork of the Viewers repo rather than as standalone plugins, start there; it walks you to a workspace and then sends each plugin back through this page.
- Package manager (yarn → pnpm) and Build tooling (Webpack → Rspack), with its 3.14 follow-up .rspack and Rsbuild — the monorepo-level moves the plugin contract mirrors.