Development Workflow

A custom front-end is a C# library that the h5 compiler transpiles into a JavaScript bundle. The Curiosity CLI uploads the bundle to a workspace, which then serves it instead of (or alongside) the default UI.

Prerequisites

Install both global dotnet tools:

dotnet tool update --global h5-compiler
dotnet tool update --global Curiosity.CLI

Verify:

h5-compiler --version
curiosity-cli --help

1. Download the project template

Inside your workspace, go to Management → Interfaces → Download template. The zip contains:

A .NET project referencing Tesserae, Mosaik.FrontEnd.Core, and the Curiosity component package.
A wwwroot/ folder for static assets.
Program.cs with a stubbed App initialization.

The template pins the h5 version that matches your workspace — don't bump it manually unless you've upgraded the workspace too.

2. Build locally

dotnet build

h5 emits the JS bundle into bin/Debug/netstandard2.0/h5/. That h5/ directory is the unit of deployment.

3. Serve and iterate against a remote workspace

Use the CLI's serve command to host your local bundle while connecting to a running workspace (local or remote):

curiosity-cli serve -s http://localhost:8080 -p bin/Debug/netstandard2.0/h5

This:

Watches the h5/ folder, serving files over HTTP.
Patches the workspace's HTML so it loads your bundle instead of the deployed one.
Forwards API calls to the workspace.

For this to work, the target workspace must allow CORS from the dev server. Set MSK_CORS to a list including http://localhost:5000 (or whichever port the CLI prints) and restart the workspace.

4. Deploy

When the local iteration is done, upload the bundle:

curiosity-cli upload-front-end -s https://workspace.example.com -t $CURIOSITY_TOKEN -p bin/Debug/netstandard2.0/h5

Under the hood the CLI calls graph.UploadNewApplicationInterfaceAsync(path, autoPatch: false) — the same method you can invoke from a connector or admin script if you'd rather deploy the bundle as part of CI.

Flags you'll use:

Flag	Default	Meaning
`-s`	-	Target server URL.
`-t`	-	An API token with permission to manage interfaces.
`-p`	`pwd`	Local path to the `h5` bundle folder.
`-a`	`false`	Auto-patch: rewrite asset URLs at upload time (set when assets live at a different prefix).
`-i`	`false`	Ignore TLS certificate errors (dev only).

5. Promote across environments

Treat the bundle as a build artifact:

CI builds the bundle (dotnet build -c Release) and uploads to dev.
On promotion to staging, re-run curiosity-cli upload-front-end against the staging workspace.
After validation, promote the same artifact to production.

Don't rebuild between staging and production — upload the byte-identical bundle so the only variable is the target workspace's data and configuration.

Troubleshooting

Symptom	Likely cause
`serve` returns CORS errors	`MSK_CORS` doesn't include the dev-server origin; restart the workspace after change.
Routes 404 after upload	`Router.Register` ran before the route was needed; check the `App.DefaultRouting.Define()` ordering.
Stale UI after upload	The browser cached the previous bundle. Hard reload, or bump the `MSKWWWHash` query string.
`h5-compiler not found`	Add `~/.dotnet/tools` to `PATH`.
Workspace says interface upload requires admin	The token used must have admin scope; create one under API integrations with Admin ticked.