Shell layout regions
The named regions of the Shell, which one each contribution reaches, and which are host-owned chrome you cannot touch.
Shell layout regions
Use the table below to choose where your App screen, menu item, or widget belongs. Core supplies the layout; your App supplies the content. For a working screen, follow Build an App screen.
Choose a destination
| What you are adding | Where it appears | Contract or guide |
|---|---|---|
| A Resource page | Work Desktop | ShellResourceContribution in the generated Resource module |
| A custom App page | Work Desktop | Manifest pageElementsExtras() |
| A menu destination | App Menu | Add a menu destination |
| App settings | App Menu → Settings | Add a settings page |
| A dashboard widget | A user's dashboard | Add a Dashboard Widget |
| Content inside an existing surface | A documented slot | Add a Slot Widget |
| A searchable destination | Command Palette | Command Palette |
Core provides one App Launcher tile for each available App. The top bar, utility dock, and status bar are host-owned; an App does not replace them.
Route Surface and Work Surface
A Route Surface is the screen mounted for a URL or work tab. Its Work Surface arranges the primary content and an optional Inspector. The page owns record selection and decides what the Inspector displays.
For a list with organization scope, place NxOrganizationTargetSelector in the page frame's organizationScope slot. Use useOrganizationListScope with the page's exact read permission. Common-data pages need no selector; custom relationships and pages combining permissions may keep their own URL adapter. Detail and edit screens display the record's stored owner.
Organization scope is page-owned. It is separate from status, type, and date filters in the ResourceTable. See Tenant and context for supported scopes and request parameters.
Side navigation follows the focused route
One side navigation area displays the menu for the focused work tab:
| Route | Menu |
|---|---|
/apps/{key}/* | That App's menu |
/settings/* | Host settings |
/workbench/{root}/* | The selected Workbench context |
/content/* | Information |
Register an App navigation item with contextId: 'app'. App settings stay in this menu. Registering a route alone does not create a menu item; declaring a menu item alone does not implement its screen.
The host handles collapsing the menu and displaying it as a drawer on narrow screens. App pages use the same route and contribution contracts in both layouts.
Widgets use registered slots
A Slot Widget renders only where the host has declared a matching slot key and API version. Declare the descriptor and register its exact component name from your App frontend entry; Add a Slot Widget owns the slot inventory and implementation steps.
For My Profile, use the current ProfileSlotPropsV2 contract, including its optional workContext. Legacy V1 widgets remain accepted in the older slots; Organization and Documents slots require V2. My Profile always refers to the authenticated person, so it does not accept an arbitrary target-person identifier.
Approval composer forms use a separate versioned contract. See Electronic Approval before implementing one.
Check the result
Open the App route directly and from its menu. Both should render the same screen inside the Shell. On a list, changing organization scope should affect that page's query; selecting a record should update that page's Inspector.
If a route or widget is missing, check the declared destination and component registration first, then the App's App lifecycle and the actor's permissions.