Skip to main content
Version: 3.14 Beta (Latest)

Building OHIF extensions with an agent

This page is normative. It states the extension contract precisely so an agent can author, build, and install an OHIF v3 extension without reading the host source. It is emitted into the docs llms.txt / llms-full.txt bundle, so an agent may ingest it directly. Every rule below is enforced by the host at registration or load time; violating one produces the errors in the Failure modes table.

Ground truth​

Run pnpm create ohif and treat its output as the canonical implementation of everything below. The always-green reference is https://github.com/OHIF/extension-example.

When this page and generated code disagree, the create-ohif output wins — it is built and tested against the current host; this page describes it.

What the host does when it loads a plugin is specified in the runtime plugins specification; the create-ohif template follows it.

The extension object (default export)​

src/index default-exports a plain object matching the Extension interface (platform/core/src/extensions/ExtensionManager.ts):

export interface Extension {
id: string;
preRegistration?: (p: ExtensionParams) => Promise<void> | void;
getHangingProtocolModule?: (p: ExtensionParams) => unknown;
getCommandsModule?: (p: ExtensionParams) => CommandsModule;
getViewportModule?: (p: ExtensionParams) => unknown;
getUtilityModule?: (p: ExtensionParams) => unknown;
getCustomizationModule?: (p: ExtensionParams) => unknown;
getSopClassHandlerModule?: (p: ExtensionParams) => unknown;
getToolbarModule?: (p: ExtensionParams) => unknown;
getPanelModule?: (p: ExtensionParams) => unknown;
onModeEnter?: (p: AppTypes) => void;
onModeExit?: (p: AppTypes) => void;
}
  • id is the only required field.
  • Every other field is optional. An extension supplies only the module getters it implements.
  • registerExtension is async and awaits preRegistration before registering any module, so preRegistration may perform async setup.
  • Registration throws Extension ID not set if id is missing or falsy.
  • A duplicate id is skipped with a warning (not an error): the second registration returns early without duplicating modules.

id MUST equal the package name (normative)​

The runtime loader caches loaded modules by packageName, and Mode dependency resolution re-resolves bare package names, so the extension id MUST equal the name field in package.json. Derive it — never hardcode a divergent string:

src/id.ts
import packageJson from '../package.json';

const id = packageJson.name;

export { id };

If id !== package.json name, the extension may register in a build-time host but will fail to resolve as a Mode dependency and will not be found by the runtime loader.

Module getter signature​

Every get*Module function is called with exactly this params object (ExtensionManager.ts):

{ appConfig, commandsManager, servicesManager, hotkeysManager, extensionManager, configuration }

hotkeysManager is passed at runtime even though the published ExtensionParams type does not list it — this is the runtime truth; you may rely on it.

Access services through servicesManager.services (destructure by name). Subscribe with service.subscribe(EVENT, cb) and unsubscribe on cleanup; prefer pub-sub over polling effects.

The name rule for module entries​

Except for commandsModule, every element returned by a module getter MUST have a name. The manager iterates the returned array and throws Extension ID <extensionId> module <moduleType> element has no name for any element missing one.

Each registered element is keyed as:

`${extensionId}.${moduleType}.${element.name}`

The moduleType is one of the 12 module types (platform/core/src/extensions/MODULE_TYPES.js):

ConstantmoduleType string
COMMANDScommandsModule
CUSTOMIZATIONcustomizationModule
STATE_SYNCstateSyncModule
DATA_SOURCEdataSourcesModule
PANELpanelModule
SOP_CLASS_HANDLERsopClassHandlerModule
TOOLBARtoolbarModule
VIEWPORTviewportModule
CONTEXTcontextModule
LAYOUT_TEMPLATElayoutTemplateModule
HANGING_PROTOCOLhangingProtocolModule
UTILITYutilityModule

commandsModule is the exception: its shape is { actions?, definitions, defaultContext? }. defaultContext defaults to 'VIEWER' when omitted, and its entries are keyed by command name inside that context rather than by an element name.

Build contract (v1 = UMD)​

A v1 plugin is a UMD bundle. The build sets output.library to:

{ name: pkg.name, type: 'umd' }

so the bundle assigns its whole module to window['@scope/name'] (the global keyed by the full package name): the extension as default, plus every named export. The host registers default; another plugin can import the named exports.

The following are externals: the build leaves them for the host to provide, and a plugin must never bundle or import its own copy. The host provides most of them as globals; the exceptions are noted below.

[/\b(vtk.js)/, /\b(dcmjs)/, /\b(gl-matrix)/, /^@ohif/, /^@cornerstonejs/, 'react', 'react-dom', 'react/jsx-runtime', 'react-router', 'react-router-dom', 'i18next', 'react-i18next']

The host assigns its singleton copies to window, keyed by full package name, in two tiers.

The stable shared set (platform/app/src/runtimeShared.ts) is assigned at startup and is the contract runtime plugins can rely on across releases:

react, react-dom, react/jsx-runtime, @ohif/core, @ohif/ui-next, @ohif/i18n, @ohif/extension-default, @ohif/extension-cornerstone, @cornerstonejs/core, @cornerstonejs/tools, dcmjs, gl-matrix, react-router, react-router-dom, i18next, react-i18next.

@ohif/i18n is shared because runtime extensions dereference it during module evaluation. React Router and i18next are shared so a plugin uses the viewer's Router and its one i18next instance. @ohif/ui is intentionally not shared: it is legacy and a forbidden import for runtime plugins — use @ohif/ui-next.

Every extension and mode compiled into the viewer is also shared, by the generated plugin loader, once it has loaded: the whole module, default and named exports, under its package name. These carry no compatibility promise; an extension's exports can change between releases.

Most extensions built into the viewer (those marked "default": false in pluginConfig.json, such as @ohif/extension-cornerstone-dicom-sr) load only when a mode that needs them opens, so they are not on window at startup, when a runtime plugin's file runs. Within one list of plugins, the viewer loads the built-in ones before the runtime ones. So for a runtime plugin to import an extension that loads on demand, also list that extension by name in window.config.extensions; it then loads, and is shared, at startup (see Runtime plugins).

Code that runs once a mode is open can instead look things up when it needs them, with no import and no config change. Where an extension registers what you need (a utility module, a command), use extensionManager.getModuleEntry(...) or commandsManager.runCommand(...) (see Utility module). If an extension does not register what you need, ask for it to be exposed as a utility module (as @ohif/extension-cornerstone-dicom-sr does for its tool names), or build your plugin inside an OHIF checkout or a create-ohif workspace.

Anything else the externals match has no host global: vtk.js (a known v1 gap), and @cornerstonejs/* packages other than core and tools. A runtime-loaded plugin that imports one resolves it to undefined at load and breaks, so do not depend on them in a runtime plugin. A fork that builds its own viewer can add to the shared set: see Sharing more libraries from a fork.

These globals serve UMD runtime plugins, which read them from window. They do not change how an ES module plugin's imports resolve, and they do not provide types: to compile against an extension's exports, build inside an OHIF checkout or a create-ohif workspace.

Do not edit output.library or externals in the build config (.rspack/) — that is the host contract, not plugin-tunable.

package.json contract​

  • keywords MUST include "ohif-extension" (build-time discovery relies on it).
  • peerDependencies["@ohif/core"] is a range checked fail-closed against the running host, with includePrerelease. A mismatch refuses the load; keep it accurate.
  • Development fields (main / module) point at src so an in-tree or directory-mode host resolves source directly. There is no types field and no exports map in the v1 contract — the build emits a UMD bundle, not TypeScript declarations, so do not add a types entry pointing at a .d.ts file the toolchain does not produce.
  • publishConfig rewrites only main / module to dist on publish. These field overrides work only with pnpm publish — the npm CLI ignores them, so publish with pnpm.
  • files is ["dist", "src", "public", "README.md"].

Installing into a host​

There are two ways to get a built extension into a viewer.

Build-time​

Add an explicit entry to platform/app/pluginConfig.json, or run pnpm plugin add <pkg> in a Viewers checkout, then rebuild. See Extension Installation.

Runtime​

Add a descriptor to window.config.extensions in app-config.js — no viewer rebuild. See Runtime Extensions. The full descriptor:

{
packageName, // MUST equal the extension id
importPath, // URL to the built bundle
globalName, // UMD only — see rule below; ESM MUST omit it
coreVersionRange, // checked fail-closed against the host @ohif/core version
integrity, // required for cross-origin loads
styles: [], // optional CSS URLs
}
  • globalName is a strict format discriminator (C3-strict). For a UMD runtime bundle it MUST be set; the loader then returns window[globalName]. For an ESM bundle it MUST be omitted; the loader returns the module's default export. The loader never defaults globalName to packageName — omitting it on a UMD bundle yields a blank/undefined global and the load fails.
  • Origins are deny-by-default: same-origin is implicit; any other origin must be listed in window.config.runtimePluginOrigins.
  • coreVersionRange is checked before any network import; a mismatch refuses the load.
  • Every attempt — success and failure, with host-vs-required versions — is recorded on window.__ohif.runtimePlugins for agent self-diagnosis.

The normative reference for descriptor fields, the origin allowlist, the audit record shape, and the CSP/CORS requirements is Runtime Extensions and Modes.

AGENTS.md​

create-ohif ships an AGENTS.md at the package root that restates these rules for a coding agent working inside the generated project. The canonical content is below (kept byte-identical to platform/create-ohif/templates/extension/AGENTS.md):

# AGENTS.md — {{name}} (OHIF extension)

## What this package is

An OHIF v3 extension built as a UMD bundle (plugin Contract v1). The default export of
`src/index.tsx` is the extension object; its `id` MUST equal package.json `name`. The deployable
artifact is `dist/index.umd.js` (the extension's CSS is injected by that bundle at runtime).

## Commands

- `pnpm dev` — watch build (development UMD to `dist/`)
- `pnpm build` — production UMD to `dist/`
- `pnpm test` — headless contract smoke test (`src/__tests__/extension.test.ts`)
- `pnpm typecheck` — `tsc --noEmit`

## Hard rules (violating any breaks loading in the host)

1. `src/id.ts` derives `id` from package.json `name`. Never hardcode a different id.
2. Every module entry needs a `name` (the host throws otherwise). The module id becomes
`<id>.<moduleType>.<name>`.
3. Never bundle or import copies of: `react`, `react-dom`, `react/jsx-runtime`,
`react-router`, `react-router-dom`, `i18next`, `react-i18next`, `@ohif/*`,
`@cornerstonejs/*`, `dcmjs`, `gl-matrix`, `vtk.js`. They are externals
(see `.rspack/pluginExternals.js`): the build leaves them for the host to provide.
The host provides as runtime globals the stable shared set (`react`, `react-dom`,
`react/jsx-runtime`, `@ohif/core`, `@ohif/ui-next`, `@ohif/i18n`,
`@ohif/extension-default`, `@ohif/extension-cornerstone`, `@cornerstonejs/core`,
`@cornerstonejs/tools`, `dcmjs`, `gl-matrix`, `react-router`, `react-router-dom`,
`i18next`, `react-i18next`) plus every extension and mode compiled
into the viewer once it has loaded, shared as-is with no compatibility promise.
Most extensions load only when a mode needs them; for a runtime extension to
import one, the deployer also lists it by name in `window.config.extensions`,
which loads it first. Anything
else these patterns match, such as other `@cornerstonejs/*` packages or `vtk.js`,
has no host global: a runtime-loaded extension that imports it resolves it to
`undefined` at load and breaks. To use code another extension registers, prefer
`extensionManager.getModuleEntry(...)` over importing it.
4. Never import `@ohif/ui` — it is legacy and the host does not provide it to runtime plugins.
Use `@ohif/ui-next`.
5. Do not edit `output.library` / `externals` in `.rspack/` — that is the host contract.
6. Keep `keywords: ["ohif-extension"]` and the `@ohif/core` peerDependency range accurate. The
host does not read the peer range; it refuses to load a runtime extension whose
`coreVersionRange` (in its runtime descriptor, see README.md) does not match the host
version, so keep that value in step with the peer range.
7. Keep package.json `module` pointing at `src/index.tsx` — directory-mode loading
(pluginConfig `directory`) resolves the package through that field.
8. CSS is injected at runtime by the bundle (style-loader), self-contained (Tailwind scans only
this package; preflight stays off). Never rely on host stylesheets.
9. Publish with `pnpm publish` (publishConfig field rewrites do not work with the npm CLI).

## Module map

| File | Module type | Registered id |
| --------------------------------- | --------------------- | ------------------------------------------ |
| src/getViewportModule.tsx | viewportModule | `{{name}}.viewportModule.example` |
| src/getPanelModule.tsx | panelModule | `{{name}}.panelModule.examplePanel` |
| src/commandsModule.ts | commandsModule | commands in context `DEFAULT` |
| src/getSopClassHandlerModule.ts | sopClassHandlerModule | `{{name}}.sopClassHandlerModule.example` |
| src/getToolbarModule.tsx | toolbarModule | `{{name}}.toolbarModule.evaluate.*` |
| src/getHangingProtocolModule.ts | hangingProtocolModule | `{{name}}.hangingProtocolModule.example` |

(Only the module types selected at scaffold time exist in this checkout.)

## Adding functionality

- Command: add to `definitions` in `src/commandsModule.ts` (defaultContext `DEFAULT`).
- Panel: `{ name, iconName, iconLabel, label, component }` in `src/getPanelModule.tsx`.
- Viewport: `{ name, component }` in `src/getViewportModule.tsx`.
- Hanging protocol: `{ name, protocol }` in `src/getHangingProtocolModule.ts` (auto-registered
with the HangingProtocolService when `protocol` is present).
- Another module type: create `src/get<Type>Module.ts(x)` with a default-exported getter and add
it as a property of the object in `src/index.tsx`.

## Services

Access via `servicesManager.services` (destructure by name). Subscribe via
`service.subscribe(EVENT, cb)` and unsubscribe on cleanup; prefer pub-sub over polling effects.

## Testing

`pnpm test` runs the headless harness (`src/__tests__/harness.ts` — mock managers mirroring the
host's registration contract, no browser, no `@ohif/core` install). Rendering cannot be tested
here — see docs 'Building OHIF extensions with an agent' → Testing for the viewer-in-docker +
Playwright flow.

## Reference

- Contract: https://docs.ohif.org/platform/extensions/building-with-agents
- Reference implementation: https://github.com/OHIF/extension-example

Testing​

create-ohif ships a headless contract smoke test. It constructs the real @ohif/core manager stack (or mock managers mirroring the same registration contract), registers the extension exactly as the app does, and asserts that:

  • the extension id equals package.json name and registers exactly once;
  • each shipped module element is registered under <id>.<moduleType>.<name>;
  • shipped commands are registered in their context;
  • a shipped hanging protocol is added to the HangingProtocolService;
  • a shipped default customization exposes its declared slots.

Run it with pnpm test. Because it exercises the real registration path (not mocks of it), removing a name from a module element makes the test fail with the host's own element has no name throw — the same failure a deployed host would produce.

What the smoke test cannot prove​

The headless harness has no browser and no GPU. It cannot verify:

  • cornerstone / WebGL rendering, or any pixel output;
  • actual viewport mounting in the grid;
  • hanging-protocol layout execution against real studies;
  • Tailwind styling and the compiled dist/index.css;
  • DICOMweb data loading;
  • toolbar and hotkey interaction.

E2E fallback​

To prove rendering and interaction, run a viewer host with the plugin installed and drive it with Playwright:

  • Build-time: in a Viewers checkout, pnpm plugin add <pkg> then pnpm dev.
  • Runtime: serve the built bundle against the released docker image with a /plugins/ mount and a runtime descriptor.

Contributors working inside the Viewers monorepo should follow .agents/skills/ohif-test-agent/SKILL.md for the fixture system and page objects. A minimal Playwright assertion loads a study and checks that the extension's own UI (for the reference extension, its overlay text) is visible.

Failure modes for agents​

SymptomCauseFix
Bundle loads but window[globalName] is undefined / blankoutput.library.name wrong, or a UMD runtime descriptor omitted globalNameSet output.library.name = pkg.name; set globalName on UMD runtime descriptors (never on ESM)
Throws Extension ID not setDefault export has no id (or id is falsy)Derive id from package.json name in src/id.ts
Throws ... module <type> element has no nameA module getter returned an element without nameAdd a name to every element (all types except commandsModule)
Load refused before any network requestcoreVersionRange (runtime) or peerDependencies["@ohif/core"] (build) does not satisfy the host versionWiden/correct the range to include the host @ohif/core version; inspect window.__ohif.runtimePlugins for host-vs-required versions
Runtime load refused with an origin messageBundle origin not in the allowlistAdd the origin to window.config.runtimePluginOrigins (same-origin is implicit)
Extension registers build-time but is not found as a Mode dependency or by the runtime loaderid !== package.json nameMake id equal the package name
UI renders unstyledTailwind content gap — CSS not compiled into a self-contained dist/index.css, or reliance on host stylesheetsCompile self-contained CSS into dist/index.css; do not depend on host styles
Duplicate/missing modules after registering twiceDuplicate id is skipped with a warning, not an errorEnsure each extension id is unique