App Metadata

An App is a logical container that bundles objects, views, pages, and dashboards into a cohesive application experience. It defines the navigation structure, branding, and access permissions.

Basic Structure

const crmApp = {
  name: 'crm',
  label: 'CRM',
  version: '1.0.0',
  description: 'Customer Relationship Management',
  icon: 'briefcase',
  active: true,

  branding: {
    primaryColor: '#1a73e8',
    logo: '/assets/crm-logo.svg',
    favicon: '/assets/favicon.ico',
  },

  navigation: [
    { type: 'object', label: 'Accounts', objectName: 'account', icon: 'building' },
    { type: 'object', label: 'Contacts', objectName: 'contact', icon: 'users' },
    { type: 'object', label: 'Opportunities', objectName: 'opportunity', icon: 'trending-up' },
    { type: 'dashboard', label: 'Sales Dashboard', dashboardName: 'sales_overview', icon: 'bar-chart' },
  ],

  requiredPermissions: ['crm_access'],
};

App Properties

Property	Type	Required	Description
`name`	`string`	✅	Machine name (`snake_case`)
`label`	`string`	✅	Display name
`version`	`string`	optional	App version
`description`	`string`	optional	App description
`icon`	`string`	optional	App icon (Lucide/Material)
`active`	`boolean`	optional	Is app active (default: `true`)
`isDefault`	`boolean`	optional	Is default app
`navigation`	`NavigationItem[]`	✅	Navigation tree
`branding`	`AppBranding`	optional	Visual customization
`requiredPermissions`	`string[]`	optional	Required permissions to access
`homePageId`	`string`	optional	Custom home page ID
`objects`	`string[]`	optional	Objects included in this app
`apis`	`string[]`	optional	API endpoints included
`mobileNavigation`	`object`	optional	Mobile-specific navigation

The navigation tree supports five item types, combined to create rich menu structures:

Links to an object's list view:

{ type: 'object', label: 'Accounts', objectName: 'account', icon: 'building', viewName: 'all_accounts' }

Links to a dashboard:

{ type: 'dashboard', label: 'Analytics', dashboardName: 'sales_overview', icon: 'bar-chart' }

Links to a custom page:

{ type: 'page', label: 'Settings', pageName: 'app_settings', icon: 'settings', params: { tab: 'general' } }

Links to an external URL:

{ type: 'url', label: 'Help Center', url: 'https://help.example.com', icon: 'help-circle', target: '_blank' }

Groups items into collapsible sections with children:

{
  type: 'group',
  label: 'Sales',
  icon: 'dollar-sign',
  expanded: true,
  children: [
    { type: 'object', label: 'Accounts', objectName: 'account', icon: 'building' },
    { type: 'object', label: 'Contacts', objectName: 'contact', icon: 'users' },
    { type: 'object', label: 'Opportunities', objectName: 'opportunity', icon: 'trending-up' },
  ],
}

All navigation items share these base properties:

Property	Type	Description
`id`	`string`	Unique identifier
`label`	`string`	Display label
`icon`	`string`	Icon name
`visible`	`boolean \| string`	Visibility (boolean or expression)

Branding

Customize the visual appearance of the app:

branding: {
  primaryColor: '#1a73e8',    // Hex color code
  logo: '/assets/logo.svg',   // Logo URL
  favicon: '/assets/icon.ico', // Favicon URL
}

Property	Type	Description
`primaryColor`	`string`	Primary brand color (hex)
`logo`	`string`	Logo image URL
`favicon`	`string`	Favicon URL

Configure mobile-specific navigation behavior:

mobileNavigation: {
  mode: 'bottom',
  bottomNavItems: ['home', 'accounts', 'contacts', 'settings'],
}

Complete Example

const projectApp = {
  name: 'project_management',
  label: 'Project Management',
  version: '2.0.0',
  description: 'Track projects, tasks, and team workload',
  icon: 'folder-kanban',
  active: true,

  branding: {
    primaryColor: '#6366f1',
    logo: '/assets/pm-logo.svg',
  },

  navigation: [
    {
      type: 'page',
      label: 'Home',
      pageName: 'pm_home',
      icon: 'home',
    },
    {
      type: 'group',
      label: 'Projects',
      icon: 'folder',
      expanded: true,
      children: [
        { type: 'object', label: 'Projects', objectName: 'project', icon: 'folder' },
        { type: 'object', label: 'Tasks', objectName: 'project_task', icon: 'check-square', viewName: 'task_board' },
        { type: 'object', label: 'Milestones', objectName: 'milestone', icon: 'flag' },
      ],
    },
    {
      type: 'group',
      label: 'Reports',
      icon: 'bar-chart',
      children: [
        { type: 'dashboard', label: 'Overview', dashboardName: 'project_overview', icon: 'layout-dashboard' },
        { type: 'dashboard', label: 'Team Workload', dashboardName: 'team_workload', icon: 'users' },
      ],
    },
    {
      type: 'url',
      label: 'Documentation',
      url: 'https://docs.example.com/pm',
      icon: 'book-open',
      target: '_blank',
    },
  ],

  requiredPermissions: ['pm_access'],
  homePageId: 'pm_home',
};

Page Metadata — Custom pages referenced from navigation
Dashboard Metadata — Dashboards referenced from navigation
View Metadata — Views displayed within navigation items
Permission Metadata — Access control for apps

App Metadata

App Metadata

Basic Structure

App Properties

Navigation Items

Object Navigation

Dashboard Navigation

Page Navigation

URL Navigation

Group Navigation

Common Navigation Properties

Branding

Mobile Navigation

Complete Example

On this page