Runtime Plugins & CSP
Runtime plugins let you deploy prebuilt extension and mode bundles alongside the
viewer and load them at runtime through descriptor entries in app-config.js —
no viewer rebuild. This page covers how the official Docker/nginx image serves
those bundles, how to mount them, and the optional Content-Security-Policy
header.
For the descriptor object itself (field-by-field reference, the
runtimePluginOrigins allowlist, and the window.__ohif.runtimePlugins
audit surface) the normative reference is
Runtime Extensions and Modes
in the Configuration Files guide. See also the
Runtime Extensions overview. This
page does not restate the descriptor contract; it only documents deployment.
What the viewer guarantees when it loads a plugin is specified in the runtime plugins specification.
The /plugins/ location, its cache rules, and CSP_HEADER exist only in
images built from OHIF 3.14 or later. An older ohif/app image (including a
latest tag that still points at a 3.13 release) has no runtime loader and
ignores extensions/modes descriptors entirely. Pin a 3.14+ tag.
The /plugins/ directory convention
The image serves runtime plugins from a dedicated /plugins/ location. The
layout is:
plugins/<packageName>/<version>/<files>
<packageName>may be scoped, e.g.@acme/ohif-extension-xyz, in which case the path isplugins/@acme/ohif-extension-xyz/1.2.3/index.umd.js.<version>is a semver directory. Versioned directories are what earnsCache-Control: public, max-age=31536000, immutable— the bytes at a versioned URL are assumed never to change, so browsers may cache them indefinitely.- Unversioned paths (anything under
/plugins/that does not sit inside aX.Y.Zdirectory) are servedCache-Control: no-cache, so the browser revalidates on every load and a swap is picked up on a normal reload.
These headers come from the nginx config in the official ohif/app image
(.docker/Viewer-v3.x/default.conf.template). The caching itself happens in
each user's browser, which is why restarting the container changes nothing. A
deployment that serves /plugins/ through another server or CDN must set
equivalent Cache-Control rules itself.
Missing files under /plugins/ return 404 — they never fall back to
index.html the way the SPA route does, so the loader can distinguish a real
bundle from an HTML error page.
When PUBLIC_URL is not /, the location is prefixed accordingly (for a build
with PUBLIC_URL=/ohif/, plugins are served under /ohif/plugins/).
Referencing a plugin from app-config
Point an extensions (or modes) entry at the served URL. The descriptor
shape is:
extensions: [{
packageName: '@acme/ohif-extension-xyz',
importPath: '/plugins/@acme/ohif-extension-xyz/1.2.3/index.umd.js',
globalName: '@acme/ohif-extension-xyz',
coreVersionRange: '^3.13.0',
styles: ['/plugins/@acme/ohif-extension-xyz/1.2.3/styles.css'],
}],
globalName is required for UMD bundles, which is what pnpm create ohif
produces today: after the script runs, the loader reads the plugin from
window[globalName], and globalName is the package name (the bundle's library
name). Without it the loader treats the file as an ES module, finds no default
export, and fails with import-error. ES module bundles omit globalName.
A UMD bundle reads the libraries it does not bundle from window when its script
runs, at startup: the viewer's stable shared set, plus every extension and mode
compiled into the viewer that has loaded by then. Most extensions built into the
viewer load only when a mode needs them. If a runtime plugin imports one, for example
@ohif/extension-cornerstone-dicom-sr, also list that extension by name; its
position in the list does not matter:
extensions: [
'@ohif/extension-cornerstone-dicom-sr',
{
packageName: '@acme/ohif-extension-xyz',
importPath: '/plugins/@acme/ohif-extension-xyz/1.2.3/index.umd.js',
globalName: '@acme/ohif-extension-xyz',
},
],
The viewer loads the built-in extensions in the list before the runtime plugins, so the import finds its global. The extension is then registered from startup instead of when its mode first opens. See the build contract for the exact list of globals and what has none.
importPath must be PUBLIC_URL-prefixed when PUBLIC_URL is not / (e.g.
/ohif/plugins/@acme/ohif-extension-xyz/1.2.3/index.umd.js). Same-origin
/plugins/ URLs need no integrity and no entry in runtimePluginOrigins;
cross-origin bundles require both — see the
descriptor fields
reference. That integrity requirement applies to descriptors specifically;
build-time pluginConfig.json importPath entries and the peerImport URL
fallthrough are treated differently, per
Where integrity is enforced.
Loading a published plugin from a CDN
A plugin published to npm can also be loaded straight from a CDN that mirrors
npm, with nothing hosted by you. The bundle is the file the published package's
main points at, dist/index.umd.js:
- jsDelivr:
https://cdn.jsdelivr.net/npm/<package>@<version>/dist/index.umd.js - unpkg:
https://unpkg.com/<package>@<version>/dist/index.umd.js
Always give an exact version. A URL without one starts serving the new file at
the next publish, and the descriptor's integrity no longer matches.
window.config = {
// ...
runtimePluginOrigins: ['https://cdn.jsdelivr.net'],
extensions: [
{
packageName: '@acme/ohif-extension-xyz',
importPath: 'https://cdn.jsdelivr.net/npm/@acme/ohif-extension-xyz@1.2.3/dist/index.umd.js',
globalName: '@acme/ohif-extension-xyz',
coreVersionRange: '>=3.14.0-beta.0 <4',
integrity: 'sha384-...',
},
],
};
The CDN is a different origin from the viewer, so:
- its origin must be listed in
runtimePluginOrigins; - the descriptor needs
integrity, computed from thedist/index.umd.jsyou built and published (see Computing theintegrityvalue); - the CDN must send CORS headers, because the loader fetches the file to verify it. jsDelivr and unpkg do;
- if you set
CSP_HEADER, extend it as described under "Cross-origin plugin origins" in Extending the baseline.
- Availability. The viewer now depends on the CDN being up and still serving
that version.
integrityprotects against altered content, not against an outage. - A public origin on the allowlist. Anyone can publish to npm, and an allowlisted origin may also serve code through the URL fallthrough path, which has no integrity check (see Where integrity is enforced). Allowlisting a public CDN therefore allows every package it mirrors on that path.
For production, hosting the bundle under /plugins/ (above) remains the
recommended route; a CDN suits trials and quick deployments.
docker-compose example
Mount the host plugins/ tree read-only into the image's plugins root and
optionally set the CSP header:
services:
viewer:
image: ohif/app:latest
ports:
- '3000:80'
environment:
# Optional. Omit the variable entirely to send no CSP header. This is the
# baseline plus the additions every deployment needs (see "Extending the
# baseline"); replace pacs.example.com with your DICOMweb origin.
CSP_HEADER: "default-src 'self'; script-src 'self' 'wasm-unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://pacs.example.com; connect-src 'self' https://pacs.example.com; worker-src 'self' blob:; object-src 'none'; base-uri 'self'"
volumes:
# /plugins/<packageName>/<version>/... (read-only)
- ./plugins:/usr/share/nginx/html/plugins:ro
Content-Security-Policy (CSP_HEADER)
CSP_HEADER is unset by default: with no value, the image sends no
Content-Security-Policy response header at all, preserving the current
behavior. Set it to opt into a CSP.
The baseline
The baseline is OHIF's own reference minimum, not an external standard. It is
the strictest policy the viewer's code could run under if it had no inline
scripts, no inline styles, and a same-origin PACS. It has all three, so no
deployment runs it unchanged: every real CSP_HEADER is this string plus the
additions in the next two sections. It is written down so the additions have a
fixed starting point:
default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob:; object-src 'none'; base-uri 'self'
Value constraints (the string is spliced into an nginx double-quoted string):
- Single line.
- Must not contain double quotes, backslashes, or
$(in an nginx string,$starts a variable).
Set exactly the value above and the viewer's own inline bootstrap scripts, its
inline styles, and every request to a cross-origin PACS are blocked. A policy
that works for a typical deployment is the baseline plus the additions listed
below, with pacs.example.com replaced by your DICOMweb origin:
default-src 'self'; script-src 'self' 'wasm-unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://pacs.example.com; connect-src 'self' https://pacs.example.com; worker-src 'self' blob:; object-src 'none'; base-uri 'self'
Extending the baseline
The bare baseline is deliberately minimal and does not work for most deployments as-is. Extend it for your environment:
connect-srcis almost always required. The shipped default config points at a cross-origin CloudFront DICOMweb PACS, anddefault-src 'self'acts as theconnect-srcfallback, so the bare baseline blocks study loading. Add every cross-origin DICOMweb origin your data sources use toconnect-src.style-src 'self' 'unsafe-inline'is always required. React, the toast layer, and the viewport grid set inline styles at runtime; with nostyle-src,default-src 'self'applies and blocks them, and the viewer renders broken. This is the standard trade-off for React applications: script injection stays locked down while inline styles are permitted.img-src 'self' data: blob: <your PACS origin>is commonly needed: data/blob image URLs, plus thumbnails fetched from a cross-origin DICOMweb server.- Cross-origin plugin origins. Any origin listed in
window.config.runtimePluginOriginsmust also be in the policy, under the directive that matches how its code is loaded:- a descriptor fetches the bundle to verify its
integrity, so add the origin toconnect-src(plusscript-src blob:, below), and tostyle-srcif the descriptor'sstylescome from it. Each such descriptor requiresintegrityper the descriptor contract; - a plain URL string in
extensionsormodes(instead of a descriptor), or a URL passed topeerImport, is imported directly, so add the origin toscript-src.
- a descriptor fetches the bundle to verify its
script-src blob:for cross-origin integrity loads. A cross-origin integrity-pinned plugin is loaded by fetching the bundle, verifying its digest, and importing it through ablob:URL. That import needsscript-src blob:, which the baseline omits; add it whenever you load cross-origin plugins. The plugin's origin must also send CORS headers (the integrity fetch usesmode: 'cors'). Same-origin/plugins/bundles need neitherblob:nor CORS.- Legacy workbox CDN imports. If the service worker is ever re-enabled, it
imports workbox from
storage.googleapis.com(service-worker.js,init-service-worker.js), which the baselinescript-src 'self'blocks; that origin would then need ascript-srcaddition. The service worker is not registered today (see below), so this does not apply to current deployments.
Interim note: inline bootstrap scripts
As written, the baseline's script-src 'self' 'wasm-unsafe-eval' also blocks
the viewer's own two inline bootstrap scripts in index.html (the
window.PUBLIC_URL bootstrap and browserImportFunction), so the app itself
cannot boot under the enforced baseline. Until the automated inline-script-hash
handshake ships, a deployment that enables CSP_HEADER must interim-add
'unsafe-inline' to script-src:
script-src 'self' 'wasm-unsafe-eval' 'unsafe-inline'
Alternatively, add the per-deployment sha256-... hashes of those two inline
scripts to script-src. The hashes are build-deterministic but vary with
PUBLIC_URL (which is interpolated into both scripts), so they must be computed
per deployment. This same caveat is documented in the
CSP and CORS requirements
reference.
Service worker and caching
- The precache manifest excludes
plugins/, so a plugin baked into the image is never pinned to the app build hash. - Runtime
/plugins/fetches use a NetworkOnly route, so a service worker cache never serves a stale plugin bundle. - The service worker is not registered in the shipped viewer today
(registration is dead code in
init-service-worker.js), so the operative caching mechanism is browser HTTP caching — theno-cache(unversioned) vs.immutable(versioned) split described above. The service-worker measures are defense-in-depth for any future re-enablement.
Sharing more libraries from a fork
This section is for a fork that builds its own viewer, with its own changes to OHIF, and loads its extensions and modes as runtime plugins.
A plugin's build leaves out every import that matches @ohif/*,
@cornerstonejs/*, vtk.js, dcmjs, gl-matrix, React, React Router or
i18next. The plugin reads those from window when its script runs. The viewer
puts its shared host packages
there, and every extension and mode compiled into it. Any other import that
matches is undefined in a runtime plugin. Examples are
@cornerstonejs/adapters, @cornerstonejs/dicom-image-loader, and a library
package that exists only in your fork, such as @ohif/acme-utils.
A viewer can only share a library that is compiled into it, so sharing more means changing the viewer's build. A stock OHIF image cannot do it.
Check whether it is already shared
If the package is an extension or mode in your pluginConfig.json, it is
already shared under its package name, and you can skip the steps below. If it
is marked "default": false, also list it by name in extensions, as described
under Referencing a plugin from app-config.
Share a library
Edit these files in your fork. The examples add
@cornerstonejs/dicom-image-loader and a fork-only @ohif/acme-utils.
-
.rspack/pluginExternals.js: add the names tohostSharedPackages.const hostSharedPackages = [// ...the names OHIF shares'@cornerstonejs/dicom-image-loader','@ohif/acme-utils',]; -
platform/app/src/runtimeShared.ts: import each library and add it toshared. Keep theimport * as name from 'package';form, which the test reads.import * as cornerstoneDicomImageLoader from '@cornerstonejs/dicom-image-loader';import * as ohifAcmeUtils from '@ohif/acme-utils';const shared: Record<string, unknown> = {// ...the entries OHIF shares'@cornerstonejs/dicom-image-loader': cornerstoneDicomImageLoader,'@ohif/acme-utils': ohifAcmeUtils,}; -
platform/app/src/runtimeShared.test.js: add the names toSETTLED_LIST. -
platform/create-ohif/host-shared-majors.json, only for a package whose name does not start with@ohif/: add the major version the viewer installs (for a 0.x package, its minor).create-ohif migratethen treats the package as shared, and sets a plugin's peer range from this file."@cornerstonejs/dicom-image-loader": "5"A package named
@ohif/...gets no entry, and the test fails if you add one. These tools assume every@ohif/package is versioned with the viewer, so keep yours in the fork's tree, on the viewer's version. -
platform/docs/docs/configuration/configurationFiles.md, if your fork publishes its own docs: under "Shared host packages", add the names to the list of shared packages, and add each package whose name does not start with@ohif/to the version table, with the version from step 4. Plugin authors read that page to learn what the viewer shares. -
Run the tests, then rebuild the viewer:
# in platform/appnpx jest src/runtimeShared.test.js# in platform/create-ohifpnpm testTwo
create-ohiftests use@cornerstonejs/adaptersas their example of a package that is not shared. If you share that one, update what they expect.
A fork-only @ohif/* package is not treated as published. OHIF's published
packages are a separate list, publishedSdkPackages in
.rspack/pluginExternals.js, which you leave alone.
What you take on
- These globals are your fork's. OHIF makes no promise about them, and a plugin that needs one runs only in a viewer that shares it.
- The files can conflict when you merge from OHIF. Run the test after each merge.
- Each shared library is kept whole in the viewer's build. It loads with the other shared packages, just before the first runtime plugin.
- A plugin is built against the viewer's version of the library. Set the plugin's peer range to match it.
What it does not fix
Sharing a package shares its main entry only. A deeper import, such as
@kitware/vtk.js/Rendering/Core/Actor or a path under
@ohif/extension-default/src/, is still undefined in a runtime plugin. Import
from the package's main entry, or compile that plugin into the viewer.
Smoke checklist
Run from the repo root. Commands are PowerShell; use curl.exe (not the
PowerShell curl alias).
- Build:
docker build -t ohif/viewer:ws8 . - Fixture: a versioned bundle
@ohif-test/smoke/1.0.0/{index.umd.js,index.mjs}plus an unversionedping.js, under a hostplugins-fixture/tree. - CSP on:
(The policy is the working form from the caution above, with the CloudFront demo PACS from the image's default config as the$env:CSP_HEADER = "default-src 'self'; script-src 'self' 'wasm-unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https://d14fa38qiwhyfd.cloudfront.net; connect-src 'self' https://d14fa38qiwhyfd.cloudfront.net; worker-src 'self' blob:; object-src 'none'; base-uri 'self'"docker run -d --rm --name ohif-ws8 -p 3300:80 -e CSP_HEADER -v "${PWD}\plugins-fixture:/usr/share/nginx/html/plugins:ro" ohif/viewer:ws8
connect-src/img-srcorigin.-e CSP_HEADERwith no value passes the variable through unchanged; PowerShell 5.1 re-quotes inline values and breaks on the embedded quotes.)curl.exe -sI http://localhost:3300/ | findstr /i content-security-policy-> the exact policy string.curl.exe -sI http://localhost:3300/plugins/@ohif-test/smoke/1.0.0/index.umd.js-> 200 +text/javascript+ immutable + CSP header.curl.exe -sI http://localhost:3300/plugins/ping.js->Cache-Control: no-cache.curl.exe -sI http://localhost:3300/plugins/@ohif-test/missing/9.9.9/x.js-> 404.
- CSP off (default): rerun without
-e CSP_HEADER;curl.exe -sI http://localhost:3300/ | findstr /i content-security-policy; $LASTEXITCODE-> no output, exit 1. - Runtime extension under CSP: set the
APP_CONFIGenv to a config whoseextensions:[{ packageName, globalName, importPath: '/plugins/...' }]points at a real UMD build in the fixture ($env:APP_CONFIG = Get-Content -Raw -Encoding UTF8 .\app-config.js, then-e APP_CONFIGwith no value); openhttp://localhost:3300in a browser; assert DevTools console shows zero CSP violation reports for the plugin script, andwindow.__ohif.runtimePluginscontains a success record for thepackageName. - No stale plugin bytes after a swap:
- Assert no service worker controls the page today: DevTools console
navigator.serviceWorker.controller->null, so the only caching layer is HTTP. - Unversioned swap: overwrite
plugins-fixture\ping.jswith new content, then a normal (non-hard) reload of/plugins/ping.jsreturns the new bytes —no-cacheforces revalidation. - Versioned discipline: publish the changed plugin as
.../1.0.1/and update the descriptorimportPath; the old1.0.0URL may stay cached forever (immutable) by design.
- Assert no service worker controls the page today: DevTools console
- Teardown:
docker stop ohif-ws8and delete the fixture.
Troubleshooting
- Got HTML instead of JS. The
/plugins/location is missing (the request fell into the SPA route and returnedindex.htmlwith a 200), or the file path is wrong. Confirm the/plugins/location exists in the running nginx config and that the requested file is actually present; a genuine miss should return 404, not HTML. import-error: module evaluated but has no default export. The descriptor has noglobalName, so the loader treated a UMD bundle as an ES module. AddglobalName(the package name) to the descriptor.- A
TypeErrorsuch asCannot read properties of undefinedwhile a plugin's script runs. The plugin imports a package that the viewer does not put onwindow. Check the import against the shared host packages. If it is an extension that loads on demand, list it by name inextensions. If you build your own viewer, see Sharing more libraries from a fork. - Wrong MIME on
.mjs. nginx's stockmime.typesdoes not map.mjs; the/plugins/location declarestext/javascriptforjs/mjsexplicitly. If an.mjsbundle is served with the wrong type, the request is not being handled by the/plugins/location. - CSP violation in the console. Read the violated directive: a blocked
connect-srcmeans your DICOMweb origin, or the origin a plugin descriptor loads from, is missing from the header; a blockedscript-srcfor a cross-origin plugin meansblob:is missing (descriptors) or the origin is (the URL fallthrough path); a blocked inline script at boot means the interim'unsafe-inline'note above has not been applied. See Extending the baseline. - Stale plugin after an update. Check the
Cache-Controlon the plugin URL. A versioned URL isimmutableand will be cached indefinitely — bump the version directory and update the descriptorimportPathinstead of overwriting bytes at the same versioned URL. Unversioned URLs areno-cacheand revalidate; if they still serve stale bytes, confirm the file is served by the/plugins/location and not an intermediary cache/CDN.