Use the App Registry

What It Is

The App Registry is the mechanism by which apps inject code and UI components into the platform. Apps can register many different types of code with the platform:

• Routes
• Redirects
• Settings sections
• Top nav icons
• Sidebar menu items
• Global UI components (e.g. modals that need to be mounted at boot time)
• Tasks (e.g. non-UI code that needs to be run at boot time)
• Banners
• Dashboard panels
• Compose panes

See the Rhapsody Vision and Architecture document for more information on how the App Registry fits into Rhapsody as a whole.

Why We Need It

As the Rhapsody codebase scales, it is important to decouple the application code solving a particular customer need (e.g. the Live Feed) from the application that will run code and display the UI components. Let's look at a metaphor to highlight this need.

To highlight why an app registry is necessary, let's look at it through the lens of running a diner. Now our cook - let's call him Larry - his health has seen better days and he's not much of a people person, but he makes one of the best smashed burgers in town so customers love him. Consequently, the diner is always packed with people looking to eat some of Larry's delicious food. The diner could be run one of two ways.

The first way could be that each customer would individually have to talk to Larry and tell him what they want. Larry would be responsible for interacting with each customer directly, maintaining all of their individual orders, and fulfilling them. Naturally, running a diner this way would be disastrous. As more and more customers order, it would become increasingly chaotic for Larry to fulfill orders and maintain any semblance of organization in completing his job.

Contrast this with the second way, how diners typically work. Servers or a front counter act as an intermediary taking orders from customers and providing those orders to Larry in a single unified fashion. This enables Larry to focus on what he does best: cooking. The majority of customer management is handled by the intermediary layer.

The app registry works much like the servers or front counter in our diner metaphor. In our case, the platform is Larry who is able to fulfill orders from a fixed set of available items. The app registry handles requests from customers (or registrations from apps in our case). It handles these registrations and allows the platform to process them in a single unified fashion so the platform does not need to know nor care about the individual requesters.

How to Use It

Each app has a single entry.ts file where all registration occurs. Registering code involves calling specific functions from the @platform/app-registry package and providing the necessary information. Each registration function requires different information but are fully typed so IDEs can provide in-context documentation and auto-complete. See the App Registry doc for complete API documentation and registration examples for every registration type.

The example below provides a preview of how entities are registered via the App Registry:

// src/entries/example/entry.ts
import {
  registerNavIcon,
  registerSidebarLink,
  registerTask,
} from '@rhapsody/app-registry'

registerNavIcon({
  id: 'topNavIcon.app.example',
  bridgeLoader: () => import('./topNavIconBridge'),
  order: -2,
  displayWhenMinimized: false,
})

registerSidebarLink({
  id: 'sidebarLink.app.example',
  bridgeLoader: () => import('./sidebarLinkBridge'),
  order: -4,
})

registerTask({
  id: 'task.app.example',
  bridgeLoader: () => import('./taskBridge'),
})

// topNavIconBridge.ts
import React from 'react'
import { bootstrapAngular } from '@rhapsody/angular'
import { IconThatRequiresAngular } from './IconThatRequiresAngular/IconThatRequiresAngular'

export function render() {
  return <IconThatRequiresAngular />
}

export const shouldRender = async () => {
  await bootstrapAngular()
  return true
}

// sidebarLinkBridge.ts
import { SidebarLinkConfig } from '@rhapsody/app-registry'
import AnalyticsIcon from 'path/to/analytics.svg'

export const config: SidebarLinkConfig = {
  icon: AnalyticsIcon,
  to: '/analytics',
  title: 'Analytics',
  otherPaths: ['/reports'],
}

export const shouldRender = true

// taskBridge.ts
export function executeTask() {
  console.log('Executed task')
}