Skip to content

The viewer page

View as Markdown

NiiVueKit does not draw anything itself. It loads a web page that runs NiiVue, and talks to it. You choose where that page comes from:

  • The ready-made page that ships inside NiiVueKit. There is nothing to set up in Xcode, but you get medgfx’s page as it is.
  • Your own page, copied into your app when it builds. It takes a little more setup, and you decide what the page does.

Using the ready-made page

Build it once from the repository root:

Terminal window
packages/niivue-swift/scripts/build-web.sh

The script builds medgfx’s web app and copies it into the package, under Sources/NiiVueKit/Resources/WebApp. Then point the bridge at it:

let bridge = Bridge(config: .niiVueKitBundled)

The copy is kept out of git, because every build has new file names and would grow the history. Run the script once per clone, and again when NiiVue, Web bridge or medgfx’s web app change. swift build and swift test work without it.

Shipping your own page

1. Write the page. It creates a NiiVue viewer, hands it to a bridge and sends ready when it is set up. Web bridge shows the smallest page that works. Web bridge is not on npm either, so the page lives in this repository too, like medgfx’s page in apps/medgfx/web.

2. Copy the built page into your app as a folder named WebApp. medgfx does this with a Run Script build phase:

Terminal window
DEST="$BUILT_PRODUCTS_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/WebApp"
mkdir -p "$DEST"
rsync -a --delete "$SRCROOT/web/dist/" "$DEST/"

Copy the whole folder rather than adding the files to Xcode one by one: the build gives them new names every time. medgfx’s phase also builds the page first, with bunx nx build medgfx-web. Xcode runs build scripts with a short PATH, so a script that calls bunx has to add ~/.bun/bin to it. medgfx also turns off User Script Sandboxing, which would otherwise stop the script from reading ~/.bun.

3. Use the default settings, which look for WebApp/index.html in your app:

let bridge = Bridge(config: .default)

Reloading the page live while you work

Point Debug builds at your web dev server, and changes to the page show up without rebuilding the app:

let bridge = Bridge(config: BridgeConfig.default.withDevServer(port: 8083))

Debug builds now load http://localhost:8083/. Release builds ignore it and always use the bundled page. Start the dev server before the app; medgfx’s page runs with bunx nx dev medgfx-web.

A few things have to be in place for this to work:

  • The dev server must send the two headers described in the next section. medgfx’s Vite config shows how.
  • A sandboxed Mac app needs the Outgoing Connections (Client) capability (com.apple.security.network.client) to reach the server.
  • The app’s Info.plist needs an App Transport Security exception for localhost, because the dev server uses plain http.

Why the page is not loaded as a file

The bundled page loads from niivue-app://app/index.html rather than from a file. A file cannot carry response headers, and the page needs two of them, Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy, before the browser lets it use SharedArrayBuffer. That is how NiiVue and its extensions share memory with workers. NiiVueKit serves every file of the page with those headers.

Changing names and folders

BridgeConfig holds the names both sides must agree on. By default the message handler is called niivue, the URL scheme is niivue-app, and the page is index.html in a WebApp folder of your app bundle. You can change any of them:

let config = BridgeConfig(handlerName: "viewer", bundleSubdir: "Viewer")

If you change the handler name, the page must use the same one: createBridge({ handlerName: 'viewer' }).

To load the page from somewhere else entirely, such as a small HTTP server inside your app, give the view a URL. It skips both the dev server and the bundled page:

NiiVueWebView(bridge: bridge, overrideURL: pageURL)

Showing more than one viewer

A bridge talks to one web view, so give each viewer its own Bridge and NiiVueModel. They can all use the same BridgeConfig.

When the viewer stays blank

  • With the ready-made page: run build-web.sh. Until you do, every request for the page fails with “not found” and the view stays empty.
  • With your own page: check that the built app contains WebApp/index.html.
  • In Debug, with a dev server: check that the server is running, and the sandbox and App Transport Security settings above.
  • The page shows, but nothing you send arrives, and model.lastStatus still reads “Waiting for webview…”: the page never sent ready, or its handler name does not match yours.

In Debug builds you can inspect the web view with Safari’s Web Inspector: open Safari’s Develop menu and pick the web view to see the page’s console and network requests.