Guide

App Identity

Declare the App Launcher tile, family placement, and overview destination from one block of package metadata.

Set the App Launcher tile, family, icon, and overview route in your package metadata. If you have not generated the package yet, start with Create an App Package; it writes the identity and manifest together.

Configure the tile

Edit extra.nexia.app in the App's composer.json. This excerpt from packages/expenses/composer.json shows its current identity and placement:

Code example

JSON

{
  "manifest": "Amuzcorp\\Nexia\\Expenses\\ExpensesAppManifest",
  "app_family": "finance",
  "app_icon": "receipt",
  "launcher_order": 20,
  "overview_navigation_id": "expenses",
  "app_name": "Expenses",
  "app_key": "expenses",
  "app_table_prefix": "expense",
  "prerequisite_apps": [],
  "readiness": "beta"
}123456789101112

Keep the package's localized descriptions alongside these fields. Choose app_key and app_table_prefix before generating Resources: later changes affect stored identities, permissions, routes, and tables.

Connect overview_navigation_id to an actual Add a menu destination. Expenses returns an item with id: 'expenses', route: '/apps/expenses', and groupId: null from ExpensesAppManifest::navigationItems(). Its pageElementsExtras() binds that route to ExpensesOverviewSurface. Register the frontend component as described in Build an App screen.

Confirm the result

Refresh package discovery and open the launcher in a tenant where the App is operational. The tile appears in Finance, uses the receipt icon, and opens its overview. The overview destination must resolve to the registered component; package metadata alone cannot make a blank route work. Check actor visibility and the destination's API authorization separately.

Fields that affect behavior

Field	Developer choice
`app_key`, `app_table_prefix`	Stable namespace and table ownership; coordinated migration required for later rename
`app_family`, `launcher_order`	Family membership and ordering within that family; the host owns family order
`app_icon`, `descriptions`	Tile presentation
`overview_navigation_id`	Existing destination supplying overview navigation
`prerequisite_apps`	Installation prerequisites; no authority to read another App's records
`readiness`	`available`, `beta`, or `preview`; use the current SDK installability rules

packages/app-sdk/packages/laravel/src/AppRuntime/AppDefinition.php validates these values. The App manifest owns the full metadata schema, defaults, readiness gates, and source discovery contract.

Central distribution policy decides publisher classification, publication, visibility, and tenant entitlements. Declaring a package identity cannot make the App official or publish it. Compatibility is separate: New App scaffolds require SDK ^0.5.0 and declare extra.nexia.core_version: ^0.5.0; the host lock selects exact installed releases.