Skip to main content

App Manifest

Overview​

CargoXplorer Apps extend the functionality of the CargoXplorer platform by allowing developers to add custom features and integrations. This guide provides step-by-step instructions on how to build and deploy a CargoXplorer 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" # Semver versioning
repository: "https://github.com/my-org/my-app.git"
branch: "main" # Optional, defaults to "main"
icon: "icon.png" # Optional

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.
  • branch: The branch of the app's repository. (Optional, defaults to "main")
  • icon: The path to the app's icon file.

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/
└── CustomOrder/
    ├── Components/
    │   ├── CustomOrderList.yaml
    │   ├── CreateCustomOrder.yaml
    │   ├── CustomOrderForm.yaml
    │   └── ListCustomOrders.yaml
    ├── Workflows/
    │   ├── Webhooks/
    │   │   └── order_created.yaml
    │   ├── API/
    │   │   └── fetch_orders.yaml
    │   └── Documents/
    │       └── custom_invoice.yaml
    └── Main.yaml  # Main Module Definition

Component Files and Naming​

Component files are YAML files that define the UI components of your app. They should be placed in the Components directory within your app's modules directory.

  • Naming Conventions: Use consistent and descriptive names for components.
  • File Structure: Each component file should define a single component and match the name of the file. This is important as it is used to identify the component file during Git operations.
    • CustomOrderList.yaml -> CustomOrder/CustomOrderList
    • CreateCustomOrder.yaml -> CustomOrder/CreateCustomOrder

Workflow Files​

Workflow files define the automated processes that are part of the app. Place all workflow files in the Workflows directory within your module folder. You can organize workflows into subdirectories based on their functionality, such as Webhooks, API, or Documents.

Guidelines:​

  • Naming Conventions: Use descriptive names for your workflow files to indicate their purpose.
  • File Contents: Each workflow file should define a single workflow, including triggers, actions, and conditions.

Repository Structure​

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

my-app-repository/
├── app.yaml
├── README.md
└── modules/
    └── CustomOrder/
        ├── Components/
        │   ├── CustomOrderList.yaml
        │   ├── CreateCustomOrder.yaml
        │   ├── CustomOrderForm.yaml
        │   └── ListCustomOrders.yaml
        ├── Workflows/
        │   ├── Webhooks/
        │   │   └── order_created.yaml
        │   ├── API/
        │   │   └── fetch_orders.yaml
        │   └── Documents/
        │       └── custom_invoice.yaml
        └── Main.yaml

Best Practices​

  • Consistent Terminology: Use consistent terms throughout your app files and documentation to avoid confusion.

  • Organize Files Logically: Keep your components and workflows well-organized using subdirectories and clear naming conventions within the modules structure.

  • Comprehensive Documentation: Use the README.md file to provide detailed documentation, including setup instructions, features, and usage examples.

  • Version Control: Use semantic versioning in the version field of app.yaml to track changes and updates to your app.

  • Regular Updates: Keep your app updated with the latest CargoX platform features and best practices. Regularly review and refactor your code as needed.