Skip to main content
Version: 3.14 Beta (Latest)

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.

The fastest path is to not migrate at all

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):

.webpack/webpack.prod.js (CLI-era — BEFORE)
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:

package.json (2026 contract — AFTER)
{
"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.types and no exports map. The plugin toolchain does not emit .d.ts files, so there is nothing to point a types field at, and the host resolves the UMD via main/module, not an exports map. Adding either would advertise a file no build step produces.
  • files ships src as well as dist because directory-mode consumers compile from source.
  • keywords carries ohif-extension (or ohif-mode for a mode) — registry discovery and pnpm plugin doctor key off it. Migrate also reads it to tell an extension from a mode, as pnpm run plugin add does. 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/ or modes/), 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 own repository if 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 —

dependencies.json (CLI-era — BEFORE)
"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-merge are dropped; the .rspack toolchain lives in devDependencies. 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 the create-ohif version (for 3.14, >=3.14.0-beta.0 <4). Starting at beta.0 keeps the range open to a viewer on an earlier beta than create-ohif. pnpm run plugin doctor checks the @ohif/core peer against the viewer's version; the runtime loader checks a descriptor's coreVersionRange, not peer ranges.
  • Shared packages follow the host's major version. The host shares React and react-dom 19, react-router and react-router-dom 6, i18next 19, react-i18next 12, @cornerstonejs/core and @cornerstonejs/tools 5, dcmjs 0.52 and gl-matrix 3 (create-ohif's host-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.0 becomes ^19.2.0), since an exact peer is met by that one release only. Any of them under dependencies move to peerDependencies by 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 under devDependencies, 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 and react-i18next are 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 are undefined: see Sharing more libraries from a fork. Cornerstone releases its packages together, so when migrate moves your @cornerstonejs/core to another major, it flags each of them still on your old one.
  • @ohif packages are peers too. An @ohif/* entry under dependencies moves to peerDependencies at the host range, as does a workspace:* entry under devDependencies, 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/ or modes/ 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 of platform/app and the SDK packages. @ohif/* entries become workspace:* 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/ui peer if present. @ohif/ui is 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/app peer if present. The host is the app, and the published @ohif/app is 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-default and @ohif/extension-cornerstone are published as libraries (see Published packages). A peer on any other @ohif package, 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 in window.config.extensions), or an extensionManager.getModuleEntry(…) lookup instead.

scripts​

migrate rewrites dev, build and build:package to the .rspack builds. It also:

  • drops dev:my-extension and dev:cornerstone, the CLI templates' aliases for dev, while they are unchanged (nothing calls them);
  • rewrites any remaining yarn run … call, or yarn <script>, to pnpm run …, and flags any other yarn call (for example yarn 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 its packages: list, set autoInstallPeers: false and merge in the allowBuilds entries from the nested files.
  • In the root .npmrc, set auto-install-peers=false.
  • Delete each package's pnpm-workspace.yaml and .npmrc, and any pnpm-lock.yaml an 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:

.rspack/rspack.prod.js (2026 contract — AFTER)
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 —

.webpack/webpack.prod.js (CLI-era — BEFORE)
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:

.rspack/pluginExternals.js (2026 contract — AFTER)
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 ofUse
useAppConfig from @state, to read the app configextensionManager.appConfig
history from @ohif/app, to navigateuseNavigate() from react-router-dom
preserveQueryParameters or preserveQueryStrings from @ohif/appYour own copy (it's a short function), or URLSearchParams
An @ohif/ui-next/lib/… or @ohif/ui-next/components/… subpathThe same export from @ohif/ui-next itself
Anything else under @, @components, @hooks or @routesWhat @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 into platform/app/pluginConfig.json. Delete any dead version field 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.js instead. See Runtime Extensions; the load is recorded at window.__ohif.runtimePlugins for auditing.
  • yarn cli search → the extension gallery plus npm 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.