Skip to main content
Version: 3.10.0-beta.142 (Latest)

Hosting the Web Viewer on a Custom URL Path

You can host the viewer on a subpath like /abc instead of the root /. There are two levels of customization depending on how you want to serve your static assets.

If you want to make the viewer accessible from a custom path (e.g. /abc) and don’t care where the assets are loaded from (they’ll be fetched from the root /), this setup is for you.

What You Get​

  • Viewer available at https://yourdomain.com/abc
  • All assets (JS, WASM, etc.) still loaded from the root (/app.js, /viewer.wasm, etc.)

How To Set It Up​

  1. Set routerBasename in your config file (e.g., config/myConfig.js) to /abc
  2. Build the viewer with:
APP_CONFIG=config/myConfig.js yarn build

Local Development​

APP_CONFIG=config/myConfig.js yarn dev

Advanced Setup (Custom Asset Path)​

If you want to host the viewer at /abc and serve static assets from a different location (e.g. /my-private-assets), this is a more advanced scenario.

What You Get​

  • Viewer accessible from https://yourdomain.com/abc
  • All assets loaded from https://yourdomain.com/my-private-assets/

Why This is Tricky​

Some libraries (especially ones using WASM) load assets using relative paths, which can break if not handled carefully. To solve this:

  • Set routerBasename to /abc
  • Set PUBLIC_URL to /my-private-assets/
  • Webpack will load assets from the specified public URL.

Local Development Notes​

In development, use proxy rewrites to handle relative asset paths. Example for dicom-microscopy-viewer:

proxy: {
  '/dicom-microscopy-viewer': {
    target: 'http://localhost:3000',
    pathRewrite: {
      '^/dicom-microscopy-viewer': `/${PUBLIC_URL}/dicom-microscopy-viewer`,
    },
  },
}

This ensures local development can find assets even when libraries expect them at certain paths.

Building and Serving in Production​

To build the viewer for production:

PUBLIC_URL=/my-private-assets/ APP_CONFIG=config/myConfig.js yarn build

If you're using npx serve, make sure to update serve.json:

{
  "rewrites": [{ "source": "*", "destination": "/abc/index.html" }]
}

Serve the viewer like this:

cd platform/app
mv dist abc  # Rename dist folder to match your viewer route
npx serve -c ./public/serve.json

🐳 Using Docker? You're Covered​

If you’re using our Dockerfile, you’re all set — it already handles copying specific asset folders (like dicom-microscopy-viewer) to the root:

COPY --from=builder /usr/src/app/platform/app/dist/dicom-microscopy-viewer /usr/share/nginx/html/dicom-microscopy-viewer

Keep an eye on the browser network tab for any assets that might fail to load — if any other libraries require similar treatment, you’ll need to handle those as well.

Summary​

GoalrouterBasenamePUBLIC_URLAssets Load From
Viewer at /abc, assets from //abcdefaultRoot /
Viewer at /abc, assets from /my-private-assets/abc/my-private-assets//my-private-assets/