feat(build): OHIF_ENV build profiles, out-of-tree pluginConfig.json, and a customization index

[wayfarer3130]

feat(build): OHIF_ENV build profiles, out-of-tree pluginConfig.json, and a customization index

Stacked on top of #6168 — base branch is ohifNextExtensions, not ohifReact. These two
commits were originally part of that PR and have been split out to keep the extensibility
contract PR reviewable on its own. Merge #6168 first.

Why

#6168 makes extensions and modes loadable, but the build was still hard-wired to files inside
this repo: the plugin set came from platform/app/pluginConfig.json, and every build variant was
another cross-env A=1 B=2 rsbuild build line in platform/app/package.json. A downstream
deployment had to edit files it does not own — i.e. fork — just to compile in its own plugins or
serve from its own route. That fork then pays a merge cost on every OHIF release.

This PR removes that requirement. Nothing about the default build changes.

What

1. Build profiles — OHIF_ENV=./ohif.config.json

One committed JSON file supplies the defaults for the build's environment variables
(PLUGIN_CONFIG, APP_CONFIG, PUBLIC_URL, HTML_TEMPLATE, ENTRY_TARGET, and the dev-server
proxy vars):

OHIF_ENV=./ohif.config.json pnpm run build

• An environment variable that is already set always wins, so a profile can be committed and
  still overridden for a single CI job (OHIF_ENV=./profiles/hospital.json PUBLIC_URL=/staging/ …).
• Validation is loud and dependency-free — unknown keys, wrong types, and bad publicUrl patterns
  fail the build naming the offending key. Constraints are read out of the schema
  (.rspack/schemaConstraints.js) rather than retyped, which is the drift class the existing
  parity test was written to catch.
• .rspack/loadBuildProfile.js is CJS and memoized: rsbuild.config.ts,
  writePluginImportsFile.js (which platform/app/tailwind.config.js also loads), and
  scripts/ohif-plugin.mjs all go through it, so whichever runs first applies the profile and the
  rest are no-ops. All three therefore agree on which config the build is using.

2. pluginConfig.json you own, outside this repo

PLUGIN_CONFIG (or a profile's pluginConfig) now redirects the build, Tailwind's content globs,
and every pnpm run plugin subcommand at the same config file — so plugin add can no longer edit
a file the build ignores.

A new optional "root" key in pluginConfig.schema.json lets an out-of-tree config keep short
relative paths: ./-relative directory values and its own extensions/ / modes/ folders
resolve against its tree, while OHIF's in-tree plugins keep resolving inside the checkout
(nearest root first, so a workspace's extensions/<name> shadows a same-named one in the harness).
Omitting root preserves the historical meaning exactly — no existing config changes behavior.

APP_CONFIG now also accepts an absolute path, which is how a ./-prefixed profile appConfig
lets a deployment keep its app config in its own repo.

3. The create-ohif workspace checkout is now read-only

ohif.config.json is both the committed manifest and the build profile. harness ensure derives a
gitignored pluginConfig.generated.json in the workspace and passes it as PLUGIN_CONFIG;
the app config is no longer copied into .ohif/. Nothing is written inside the checkout, so it can
be deleted and recreated at any time — and upgrading the pin picks up the new version's default
plugin set for free, because the generated file is rebuilt on top of whatever the fresh checkout
ships.

4. Schemas are published, not repo-internal

ohif.schema.json moved to platform/app/, and both it and pluginConfig.schema.json are added to
@ohif/app's files. A downstream repo can point $schema at
./node_modules/@ohif/app/ohif.schema.json and get completion and validation in its editor.

5. CUSTOMIZING.md

An index of every supported customization mechanism, ordered by cost, against the build procedure
each implies — plus a "files you should not edit, and what to do instead" table and a section aimed
at coding agents. The rule it exists to enforce: you should never have to modify a file inside this
repo to ship a customized viewer. Linked from AGENTS.md, with reference docs in
platform/docs/docs/configuration/build-profiles.md.

Testing

• platform/app/src/__tests__/buildProfile.test.js — profile resolution, env-var precedence,
  path resolution (true vs 'dot'), validation failures, and which config/root the build ends up
  with.
• platform/create-ohif/tests/scaffold.test.mjs updated for the generated-config harness flow.
• Existing pluginConfigSchemaParity.test.js still guards the hand-rolled validator against the
  schema.

Compatibility

Additive. With no OHIF_ENV and no PLUGIN_CONFIG, the build reads
platform/app/pluginConfig.json and resolves directory values against the repo root exactly as
before; "root" is optional and unset in the shipped config.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a5573b13-a7c6-4476-b9a1-32299d93d450

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ohifNextBuildProfiles

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}