UI

UI providers are under active development and are not yet stable. Breaking changes may happen between releases without warning. Feedback and bug reports are welcome via GitHub Issues .

UI providers mount static asset bundles. They can be configured directly under providers.ui or attached to an executable app as a plugin-backed app. The built-in admin UI at /admin remains available even when no public UI bundles are configured.

For new custom UIs, check in the frontend source and dependency lockfile, then declare a top-level build command in the UI manifest. Gestalt uses that command during preparation and release packaging so the deployment serves a prepared static asset root instead of rebuilding at runtime.

Configuring `providers.ui`

Mount a local UI bundle directly:


providers:
  ui:
    roadmap:
      source: ./customer-roadmap-review/ui/manifest.yaml
      path: /create-customer-roadmap-review
      authorizationPolicy: roadmap_review

Bind a named UI bundle to a plugin-backed app:


providers:
  ui:
    roadmap:
      source: ./customer-roadmap-review/ui/manifest.yaml
 
apps:
  roadmap_review:
    source: ./customer-roadmap-review/plugin/manifest.yaml
    ui:
      bundle: roadmap
      path: /create-customer-roadmap-review
    authorizationPolicy: roadmap_review

Or let the app manifest own the UI bundle and keep only the deployment mount in config:


apps:
  roadmap_review:
    source: ./customer-roadmap-review/plugin/manifest.yaml
    ui:
      path: /create-customer-roadmap-review
    authorizationPolicy: roadmap_review

With an app manifest like:


kind: app
source: github.com/acme/apps/roadmap-review
version: 1.0.0
spec:
  auth:
    type: none
  ui:
    path: ../ui/manifest.yaml

For every config field, see Config File.

Route Authorization

When a mounted UI has an authorizationPolicy, Gestalt authenticates the caller, resolves their role under that policy, and checks the UI manifest’s spec.routes[].allowedRoles before serving the matching route or its static assets.

Plugin-backed mounted UIs inherit the owning plugin’s dynamic grants when that plugin declares authorizationPolicy. They also inherit the plugin’s route-auth provider when the app declares auth.provider. Direct providers.ui bundles and the built-in admin UI use the server-wide auth configuration.

The Admin UI

The built-in admin UI is served at /admin by default. It includes operator views such as the Prometheus metrics dashboard and the app authorization workspace at /admin/?tab=members.

Use server.admin.authorizationPolicy to protect /admin, or server.admin.ui to pin /admin to a named UI bundle that ships admin/index.html. See Config File for those settings.

Building your own UI bundle

For source-authored UI bundles, keep generated output out of source control:


ui/
  manifest.yaml
  package.json
  package-lock.json
  src/
    app.tsx

Manifest

A UI manifest declares kind: ui. Source manifests must use top-level build with an output directory. spec.routes is optional unless a deployment binds the UI to an authorizationPolicy.


kind: ui
source: github.com/acme/apps/roadmap-ui
version: 0.0.1
displayName: Roadmap Review UI
description: Static UI for roadmap review.
build:
  command:
    - npm
    - run
    - build
  inputs:
    - package.json
    - package-lock.json
    - src
spec:
  assetRoot: dist
  routes:
    - path: /
      allowedRoles: [viewer, admin]
    - path: /admin/*
      allowedRoles: [admin]

build.command is an argv array. spec.assetRoot is manifest-relative and points at the generated static files, commonly out, dist, or build. Frameworks that require a server at runtime are not compatible with UI bundles because Gestalt serves static assets only.

For the full UI manifest schema, see App Manifests. For source UI build and release behavior, see Source UI builds and Releasing provider packages.

UI

Configuring providers.ui