App Manifest

Overview

CXTMS Apps extend the functionality of the CXTMS platform by allowing developers to add custom features and integrations. This guide provides step-by-step instructions on how to build and deploy a CXTMS App using a Git repository.

Steps to Deploy an App

1. Create a Git Repository: Set up a dedicated Git repository for your app. Each app should have its own repository.

2. Organize App Structure: Structure your app repository with the following core elements:

   • app.yaml file for the app manifest
   • icon.png file for the app icon (optional)
   • README.md file for app information
   • modules directory for all app modules
   • workflows directory for all app workflows

3. Define App Manifest: Create the app.yaml file in the root of your repository.

4. Create README: Add a comprehensive README.md file to your repository root.

5. Develop Modules: Create and organize your app's modules within the modules directory.

Define App Manifest

The app.yaml file defines the app's manifest and should be placed in the root of your repository. Here's an example for an app named my-app:

name: "@cargox/my-app" # Name of the app (should be unique)
description: "My App provides tools for managing custom orders efficiently."
author: "CargoX" # Your name or organization
version: "1.0.0" # Semver versioning
repository: "https://github.com/my-org/my-app.git"
icon: "icon.png" # Optional

Mobile white-label themes

Mobile white labels select a shared themeId, domain restrictions, bundle identifiers, and brand assets. The USA TRT mobile theme now uses the same primary color and light/dark background surfaces as the web configuration. Development variants may reuse the production theme and assets while using a separate domain, URL scheme, and .dev bundle identifier so both apps can be installed together.

Store-facing names come from the white-label appName; the USA TRT production app is published as USA TRT Mobile. Android production and development variants use separate application IDs and EAS submit profiles, so each variant can be uploaded to its own Google Play listing and internal track. Store submission credentials stay outside the white-label source configuration and are referenced by the submit profile.

Each white label may define a top-level mobile skin. It accepts hero (the default) or spotlight and now controls the full authenticated shell as well as the sign-in screen. The selected skin changes spacing, typography, corner radius, avatar shape, navigation selection treatment, sheets, profile settings, and organization selection. Domain-selected white labels resolve their skin at runtime; packaged white-label builds use the configured build-time skin.

The optional login block still supplies tenant-specific headline and tagline copy. Its skin remains supported as a sign-in override; when omitted, sign-in inherits the top-level skin.

skin: "hero",
login: {
  headline: "Your fleet,\non schedule.",
  tagline: "dispatch, tracking and POD in one place",
}

The mobile theme exposes semantic tokens for hero and panel surfaces, brand links and tints, fields, active navigation, hairlines, hover states, status colors, scrims, and control borders. Tenant themes can override hero, link, on-brand, panel, tint, and control-border colors while inheriting safe defaults from the accent palette. Both skins use the same authentication and navigation behavior and adapt their layout at the tablet breakpoint.

Skins also define coordinated metrics for DataGrid gutters and controls, form gutters and field spacing, and text-input height, padding, labels, and focus treatment. These metrics are applied by the mobile renderer to shared DataGrid, layout, form, and field components; app modules should not add mobile-only wrappers to reproduce them.

Key Attributes:

• name: The name of the app.
• description: A brief description of the app.
• author: The author of the app.
• version: The version of the app.
• repository: The URL of the app's repository.
• icon: The path to the app's icon file.

Managing Installed App Manifests

When an organization installs app manifests, each entry pins a source repository and branch, and can opt into automatic updates.

App Manifest Reference Fields

Field	Type	Required	Description
repository	string	Yes	Full HTTPS URL of the app's Git repository
repositoryBranch	string	Yes	Branch to install from (e.g., main, develop)
isAutoUpdateEnabled	boolean	No	When true, the platform automatically pulls the latest commit from the branch on each sync cycle. Defaults to false.

Example Configuration

appManifests:
  - repository: "https://github.com/cargoxplorer/cx-app-core"
    repositoryBranch: "develop"
    isAutoUpdateEnabled: true
  - repository: "https://github.com/cargoxplorer/cx-app-ups"
    repositoryBranch: "develop"
    isAutoUpdateEnabled: true
  - repository: "https://github.com/cargoxplorer/cx-app-fedex-v2"
    repositoryBranch: "develop"
    isAutoUpdateEnabled: true

Auto-Update Behavior

When isAutoUpdateEnabled is true, the platform syncs the app on every manifest update cycle, pulling the latest commit from the configured branch. This is recommended for staging and QA environments to keep apps current with active development. For production, set this to false and deploy from pinned tags or release branches.

Available First-Party Apps

The following apps are maintained by the CXTMS team and can be included in white-label configurations:

App	Repository	Description
cx-app-core	cargoxplorer/cx-app-core	Core platform modules shared across all organization types
cx-app-ups	cargoxplorer/cx-app-ups	UPS carrier integration — rate quotes, label generation, and tracking
cx-app-fedex-v2	cargoxplorer/cx-app-fedex-v2	FedEx v2 carrier integration — rate quotes, label generation, and tracking

README File

The README.md file should provide detailed information about the app, its features, and how to use it. Here's an example:

# My App

My App is a comprehensive solution for managing custom orders. It allows users to create, view, and track custom orders seamlessly within the CargoX platform.

## Features

- Create new custom orders with a user-friendly form.
- List and search through existing custom orders.
- Receive notifications for order updates.

## Setup Instructions

[Include setup and installation instructions here]

## Usage Guide

[Provide a brief guide on how to use the app]

App Module Files

App modules define both the UI components and workflows of your app. Place all module files in the modules directory within your repository. Organize modules into subdirectories as needed.

Example Structure:

modules/
└── name-module.yaml
└── name-2-module.yaml
└── name-3-module.yaml
└── ...

Workflow Files

Workflow files define the automated processes that are part of the app. Place all workflow files in the workflows directory within your app repository.

Repository Structure

Here's an example of the complete repository structure for a single app:

my-app-repository/
├── app.yaml
├── README.md
└── modules/
    └── name-module.yaml
    └── name-2-module.yaml
    └── name-3-module.yaml
    └── ...
└── workflows/
    └── workflow-id-1.yaml
    └── workflow-id-2.yaml
    └── workflow-id-3.yaml
    └── ...