Skip to main content
Version: 3.14 Beta (Latest)

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) reads it, resolves each entry to a source directory, generates the (untracked) pluginImports.js, and copies each plugin's static assets into dist.

note

pluginConfig.json is a hand-edited file: add, remove, or configure plugins using the fields documented below. The pnpm run plugin helper (add / remove / list / link / unlink / doctor) edits the same file for you and validates it — both workflows are equally supported. (Older docs said this file must not be edited by hand; that guidance belonged to the removed OHIF CLI and no longer applies.)

Top-level shape​

platform/app/pluginConfig.json
{
"$schema": "./pluginConfig.schema.json",
"extensions": [ /* extension entries */ ],
"modes": [ /* mode entries */ ],
"public": [ /* third-party public-asset entries */ ]
}
KeyRequiredDescription
$schemanoPath/URL of the published JSON Schema. Editors use it for completion; the build validates against it at config load and fails fast on invalid entries.
extensionsyesExtensions to make available to the build.
modesyesModes (workflows) to make available to the build.
publicnoThird-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:

FieldTypeDefaultDescription
packageNamestring—The package's real name (matches its package.json name). Required unless directory alone identifies the plugin.
defaultbooleantrueWhen 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.
directorystring—An explicit source directory for an out-of-tree plugin. See Plugin locations.
Removed field

Older configs carried a version field on entries — it was install bookkeeping for the removed OHIF CLI and never affected build resolution. It has been deleted from the repo config; remove it from yours (pnpm run plugin doctor flags it).

{
"extensions": [
// bare string form
"@ohif/extension-default",

// object form, registered by default
{ "packageName": "@ohif/extension-cornerstone" },

// present in the build but NOT auto-registered; loaded only when a
// registered mode requires it
{
"packageName": "@ohif/extension-cornerstone-dicom-seg",
"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.

packageName, importPath, globalName, and importName are interpolated into the generated pluginImports.js as JS string literals, so each is constrained to a character set that excludes quotes, backslashes, and newlines (the pattern values in pluginConfig.schema.json). The build validator enforces the same patterns and fails fast with the offending value, so a typo surfaces as a config error rather than as broken generated code.

FieldTypeDescription
packageNamestringPackage name, used to resolve the asset directory from node_modules when directory is not given.
directorystringSource directory of the assets to copy. Resolved like the extension directory field (absolute, ~-relative, or .-relative to the repo root).
importPathstringPath/URL the runtime loader import()s. Absolute (http… or /…) paths are used as-is; otherwise it is prefixed with PUBLIC_URL. Trusted, unverified — see the note below.
globalNamestringIf set, after importing importPath the loader returns window[globalName] (for UMD/global bundles).
importNamestringNamed export to return from the imported module. Defaults to default. Ignored when globalName is set.
tostringDestination subpath under dist for the copied assets.
importPath is trusted build-time configuration

An importPath is compiled into the bundle by the codegen as a direct import() of that URL. It is not subject to the runtimePluginOrigins allowlist and gets no integrity/SRI check, even when the URL is absolute and cross-origin — changing it requires editing this file and rebuilding, which is the same trust level as editing the app's source, so the build-time value is trusted outright.

Runtime-supplied URLs are held to stricter rules: see Where integrity is enforced. Point importPath at an origin you control — prefer a relative path or a PUBLIC_URL-served copy of the asset (the directory + to fields exist to copy third-party bundles into dist for exactly this reason).

{
"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.

  2. External, out-of-tree source — a checkout outside this repo (e.g. an extension scaffolded with pnpm create ohif). Add a directory field. The path may be absolute, ~-relative to the home directory, or .-relative to the repo root.

    { "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.

    { "packageName": "@acme/extension-foo" }

For the build internals behind these (alias generation, asset copying, the pnpm + Rspack migration), see the build tooling migration guide; in 3.14 the plugin aliases are merged in the root rsbuild.config.ts (see the 3.14 build tooling notes).