App Shell & UI Integration

This guide covers the two runtime systems your Cloud App uses inside the JTL platform:

AppBridge: Runtime SDK that enables bidirectional communication between your app (in an iframe) and the host environment (JTL Hub or ERP Cloud).
Platform UI: React component library for building interfaces that match JTL’s design system.

Your app’s configuration lives in two manifests. See the App Manifest for registration (identity, lifecycle, and capabilities) and the Listing Manifest for how your app appears to merchants. For authentication flows, see Authentication & Login. For calling the JTL Cloud and JTL-Wawi APIs, see Using Platform APIs.

AppBridge Communication

The AppBridge is provided by the @jtl-software/cloud-apps-core package. It establishes a secure communication channel between your app’s frontend (running in an iframe) and the host JTL environment (JTL Hub or ERP Cloud). The bridge lets your app request data (like session tokens) and call host methods. Publish/subscribe event handling is in development (see below).

Installation

npm install @jtl-software/cloud-apps-core

Initializing the AppBridge

Initialize the AppBridge before rendering your React app, then pass the instance as a prop or store it in context:

import { createAppBridge } from '@jtl-software/cloud-apps-core';
import { createRoot } from 'react-dom/client';

createAppBridge().then((appBridge) => {
	createRoot(document.getElementById('root')!).render(
		<StrictMode>
			<App appBridge={appBridge} />
		</StrictMode>,
	);
});

Initializing before render guarantees the channel is open before any component tries to use it.

Do not initialize the AppBridge inside a component (e.g., in useEffect). This can cause race conditions where components render before the bridge is ready. Always initialize it at the application entry point.

For Next.js apps that need SSR compatibility, use a dynamic import inside a client-side provider instead.

You can use AppBridge in any JavaScript frontend framework, including React, Vue, and Angular.

Communication Flow

The AppBridge creates a two-way channel: your app’s appBridge instance communicates with a corresponding hostAppBridge instance inside the JTL Cloud service. All communication is asynchronous and non-blocking. Your app continues executing while messages are delivered between the iframe and the host. There are no HTTP requests or polling involved.

API Reference

The AppBridge provides two main interfaces: methods (expose/call) and events (publish/subscribe).

Methods
Events

AppBridge methods provide a request/response channel between your app and the host. There are two directions:

Call host methods (available today): your app invokes functions the host exposes, like getSessionToken. See Environment-specific Methods for the full list.
Expose methods to the host (in development): your app registers functions that the host can invoke by name, used for things like custom calculations or data lookups.

Calling Host Methods

Invoke a function provided by JTL. The call returns a promise that resolves with the host’s result.

const sessionToken = await appBridge.method.call("getSessionToken");

Exposing Methods to the Host

In development: method.expose and method.isExposed are in active development and not yet available. This section will be updated when the API ships.

Once available, exposing methods will let the host invoke logic that lives in your app. For example, a calculateShippingCost function the ERP calls before showing a quote, or a validateOrder hook called before checkout. The shape will follow a name + handler registration pattern with a disposer for cleanup, mirroring the event subscription model.

Method API Summary

The table marks which APIs are available today and which are planned.

Method	Status	Description
`method.call(name, ...args)`	Available	Call a host method. Returns `Promise<T>`.
`method.expose(name, fn)`	In development	Register a function the host can call by name.
`method.isExposed(name)`	In development	Check whether a method is already registered.

AppBridge events cover two directions. One is available today for panels; the other is in development.

event.subscribe (available for panel entity context): listen for events the host publishes. Panels use this to react when the merchant navigates to a different entity, for example CustomerChanged on the customer view. See Reading Panel Context for the pattern and the available events.
event.publish (in development): send events from your app to the host so it can react to actions your app completes, for example order:verification:complete.

In development: Publishing events from your app to the host (event.publish), and general app-to-app pub/sub beyond the host entity-context events, are in active development. This section will be updated when they ship.

Host entity-context events follow a consistent convention: PascalCase, past-tense names (CustomerChanged), with object payloads ({ customerId }) rather than bare values.

Environment-specific Methods

JTL exposes different built-in methods depending on which environment your app is running in.

Setup Environment (JTL Hub)
ERP Environment (ERP Cloud)

These methods are available when your app loads via the lifecycle.configurationUrl during installation:

Method	Parameters	Returns	Description
`getSessionToken`	None	`Promise<string>`	Returns the current session token (contains user and tenant info)
`setupCompleted`	None	`Promise<void>`	Signals that setup is done and activates the app in the Hub

These methods are available when your app runs inside the ERP (via menu items or panels):

Method	Parameters	Returns	Description
`getSessionToken`	None	`Promise<string>`	Returns the current session token
`getCurrentTime`	None	`Promise<Date>`	Returns the current time as a Date object
`getCurrentCustomerId`	None	`Promise<string>`	Returns the id of the customer the merchant is viewing. Available to panels on the customer view. Resolves to an empty string when no customer is in context.

getSessionToken is available in both environments. It’s the primary way your frontend identifies the current user and tenant. For details on verifying session tokens on your backend, see Authentication & Login.

Reading Panel Context

Panels can read the current entity in context. On the customer view, call getCurrentCustomerId to read the current customer, and subscribe to the CustomerChanged event to be notified when it changes.

// Read the current customer on load
const customerId = await appBridge.method.call("getCurrentCustomerId");
 
// React to the merchant navigating to a different customer
const unsubscribe = appBridge.event.subscribe(
  "CustomerChanged",
  ({ customerId }) => {
    if (!customerId) return;
 
    // Load data for this customer.
  },
);
 
// Call unsubscribe() when your component unmounts

The CustomerChanged payload is an object of the form { customerId: string }. It’s emitted whenever the merchant selects a customer from the customer list, and not on unrelated views. Guard against an empty customerId before loading customer-specific data.

Naming Conventions

AppBridge APIs follow these conventions:

Host methods use camelCase verbs, for example getCurrentCustomerId.
Events use PascalCase and describe completed actions, for example CustomerChanged.
Event payloads are always objects, for example { customerId }, rather than primitive values. This lets new fields be added later without breaking existing subscribers.

Platform UI Components

JTL provides a React Component Library that matches the platform’s design system. Using these components ensures your app looks and feels consistent with the rest of the JTL interface.

Installation

npm install @jtl-software/platform-ui-react

Add the CSS import to your global stylesheet:

@import '@jtl-software/platform-ui-react/index.css';

Available Components

The library includes form controls, layout containers, and typography components. Here’s the full list: Layout components

Box , Grid , Stack , Layout , LayoutSection , Card

Form components

Button , Checkbox , Input , InputOTP , Radio , Select , Textarea , Switch , Toggle , ToggleGroup , FormGroup , Form

Data display

Text , Badge , Avatar , Table , DataTable , Progress

Navigation

Link , Breadcrumb , Tab , Dropdown

Feedback

Alert , Dialog , AlertDialog , Tooltip , Skeleton

Utility

Icon , Separator , ScrollArea , Collapsible , Popover , Sheet

Usage

Import components directly from the package:

import { Button, Card, Text } from '@jtl-software/platform-ui-react';

export default function MyComponent() {
	return (
		<Card>
			<Text>Welcome to my JTL App</Text>
			<Button
				onClick={() => console.log('clicked')}
				label='Get Started'
			/>
		</Card>
	);
}

What’s Next

Authentication & Login

Implement OAuth 2.0 and session token verification in your app.

Using Platform APIs

Call the JTL Cloud REST and GraphQL APIs from your backend.

Handling Webhooks

Respond to events and AppBridge messages.

Best Practices

Patterns for AppBridge initialization, error handling, and production readiness.

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

Vouchers API

AppBridge Communication

Installation

Initializing the AppBridge

Communication Flow

API Reference

Calling Host Methods

Exposing Methods to the Host

Method API Summary

Environment-specific Methods

Reading Panel Context

Naming Conventions

Platform UI Components

Installation

Available Components

Usage

What’s Next

Authentication & Login

Using Platform APIs

Handling Webhooks

Best Practices

​AppBridge Communication

​Installation

​Initializing the AppBridge

​Communication Flow

​API Reference

​Calling Host Methods

​Exposing Methods to the Host

​Method API Summary

​Environment-specific Methods

​Reading Panel Context

​Naming Conventions

​Platform UI Components

​Installation

​Available Components

​Usage

​What’s Next

Authentication & Login

Using Platform APIs

Handling Webhooks

Best Practices

AppBridge Communication

Installation

Initializing the AppBridge

Communication Flow

API Reference

Calling Host Methods

Exposing Methods to the Host

Method API Summary

Environment-specific Methods

Reading Panel Context

Naming Conventions

Platform UI Components

Installation

Available Components

Usage

What’s Next