Skip to content
ReferenceForDeveloper⏱ About 6 min

Modules: the front end ​

A module's screens are one JavaScript bundle (ui.bundle, usually dist/index.js), built from ui/src/index.ts. BMA loads it from the API after sign-in for organizations that have the module enabled, checks its id and version, and calls register() once.

register() ​

ts
export const id = __MODULE_ID__            // filled in by the build from module.json
export const version = __MODULE_VERSION__

export function register(h: Host) {
  setHost(h)
  return {
    routes: [],                         // extra screens, mounted under /m/<id>/…
    components: { Hello: HelloView },   // the names module.json's ui.routes[].component use
    widgets: {},                        // components for App Builder widgets (ui.widgets)
  }
}

Screens and menu items ​

json
"ui": { "bundle": "dist/index.js", "routes": [ { "path": "/hello", "component": "Hello", "title": "Hello", "permission": "hello.view" } ] },
"menu": [ { "key": "main", "title": "Hello", "route": "/hello", "parent": null, "permission": "hello.view" } ]

A menu item's route must be one of your ui.routes. parent is another of your items' key, null for the top level, or folder:<slug> for one of BMA's folders. /admin/…, /login and /store are reserved.

What the host gives you ​

host()
apiBMA's HTTP client: signed-in session, CSRF token and the API address already set; api.get('/hello/hello')
settingsyour module's non-secret settings for this organization
storesthe signed-in user (auth), app settings, view state
componentsBMA's own building blocks: QueueGridPanel, DocumentPane, GenericQueueView, ModuleBorderFrame
router, modulethe router, and your id and version
apiBasethe API address, for building links to your API paths (downloads)
workspaceopen screens in tabs, replace the current tab, the link menu, name your tab: host calls
menusetBadge(): a count on one of your menu items: host calls
shortcutslist your screen's keys on the Shift+? sheet: host calls

workspace, menu and shortcuts are newer than the rest: check they exist before you call them.

Shared libraries come from BMA, so don't bundle your own copy: vue, vue-router, pinia, vuetify (its components are available as <v-…> without imports), axios, ag-grid-community, ag-grid-vue3. Never import BMA's internals (@/…): the build refuses it.

Building ​

ui/vite.config.ts is plain data: export default { entry: 'src/index.ts', bundle: 'dist/index.js' }. Build with bin/build-modules.sh <install copy> (it also stamps checksums), or only build with cd next-src && npx tsx scripts/build-modules.ts --out-root=<dir> <id>. CSS is bundled into the JS.

After a new version is enabled, users get it on their next sign-in or reload. A tab opened before the upgrade asks for the old version; reload it.