Build the Frontend

Scaffold the React frontend for your JTL Cloud App with TanStack Router and the JTL AppBridge SDK.

Build the React frontend for a JTL Cloud App using Vite, TypeScript, TanStack Router, and the JTL AppBridge SDK. By the end, the app runs locally with three working routes and a clear state for connecting to your backend.

Stack: Vite, React, TypeScript, TanStack Router (file-based routing), JTL AppBridge, JTL Platform UI.

Prerequisites

You need:

• ✅ A JTL ID (your login to the JTL ecosystem)
• ✅ Access to an organization (tenant) in the Partner Portal (created automatically on first login)
• ✅ Node.js v24.16.0 or higher (current LTS, includes npm). Verify with node --version and npm --version

If you don’t have your JTL ID and Partner Portal access yet, follow Create a Developer Account first.

What you’re Building

Before writing code, here’s how a JTL Cloud App works:

Your frontend runs inside JTL’s App Shell (in an iframe). It communicates with the shell through AppBridge, a small SDK that exposes shell capabilities to the iframe. The most important one is getAppToken, a short-lived signed token that proves which merchant (tenant) is currently using your app. Your frontend sends that token to your backend, which verifies it and uses it to make tenant-scoped calls to the JTL API.

Not every page in your app runs inside the shell. The frontend has three routes, and they fall into two groups:

• /setup and /erp run inside the App Shell iframe. AppBridge is available, and the app knows which tenant it’s serving.
• /hub opens in a standalone browser tab when a merchant clicks the app card. There is no iframe, no AppBridge, and no tenant context.

These two contexts require slightly different setup. You’ll handle that when building the frontend.

Working with an AI coding tool? Connect the JTL docs MCP server, then paste the prompt below to scaffold the project before following the steps here.

AI Assistant Prompt

  Help me build the frontend for a JTL Cloud App. Use the jtl-docs MCP
  server for any platform details. Scaffold a Vite, React, TypeScript
  project on port 5173 with TanStack Router file-based routing. Put the
  AppBridge provider behind a pathless _shell layout so /setup and /erp
  inherit it and /hub stays outside it. 

1. Create the Project

mkdir my-jtl-app
cd my-jtl-app

npm create vite@latest frontend -- --template react-ts

When prompted:

• Ok to proceed? (y): y
• Install with npm and start now?: Yes

Once Vite finishes installing, press Ctrl + C to stop the dev server.

2. Install Packages

cd frontend
npm install @tanstack/react-router @jtl-software/cloud-apps-core @jtl-software/platform-ui-react tailwindcss @tailwindcss/vite
npm install -D @tanstack/router-plugin @tanstack/react-router-devtools

Package	Purpose
@tanstack/react-router	Type-safe router with file-based routing
@tanstack/router-plugin	Vite plugin that auto-generates the route tree from your file structure
@tanstack/react-router-devtools	Devtools panel for inspecting routes (dev only)
@jtl-software/cloud-apps-core	AppBridge SDK: communication between your app and the JTL App Shell
@jtl-software/platform-ui-react	JTL’s UI component library (Button, Card, Text, etc.)
tailwindcss + @tailwindcss/vite	Utility-first CSS, required by the JTL UI library

3. Configure Vite

Replace frontend/vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import { tanstackRouter } from '@tanstack/router-plugin/vite';
import path from 'path';

export default defineConfig({
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:5273',
        changeOrigin: true,
      },
    },
  },
  plugins: [
    // The router plugin must come before the React plugin
    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
    react(),
    tailwindcss(),
  ],
  resolve: {
    alias: {
      '/assets': path.join(
        path.dirname(require.resolve('@jtl-software/platform-ui-react')),
        'assets',
      ),
    },
  },
});

This does three things:

• TanStack Router plugin watches src/routes/ and regenerates src/routeTree.gen.ts whenever you add or rename a route file. The plugin must be listed before react(). See the installation docs for details.
• Tailwind plugin enables Tailwind utilities, which the JTL UI library depends on.
• Dev proxy forwards /api/* requests to a backend on localhost:5273. Your frontend can call fetch('/api/...') and Vite will route the request without CORS issues during development.

4. Set up Styles

Replace frontend/src/index.css:

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

5. Create the Route Files

TanStack Router uses file-based routing, so your folder structure under src/routes/ is your route configuration. Delete the default src/App.tsx (the router replaces it), then create the following structure:

frontend/src/routes/
├── __root.tsx              # Root layout (devtools, outlet)
├── _shell.tsx              # Pathless layout for routes that render inside the App Shell
├── _shell.setup.tsx        # /setup (inside App Shell)
├── _shell.erp.tsx          # /erp (inside App Shell)
└── hub.tsx                 # /hub (standalone, no AppBridge)

Two conventions are in play here:

• __root.tsx is the top-level layout, always rendered.
• _shell.tsx is a pathless layout route. The leading underscore means it doesn’t add a URL segment, so _shell.setup.tsx becomes /setup, not /_shell/setup. Any route file prefixed with _shell. shares the layout’s wrapper. hub.tsx doesn’t, so it bypasses the AppBridge initialization entirely.

Root Route

Add the following to your frontend/src/routes/__root.tsx:

import { createRootRoute, Outlet } from '@tanstack/react-router';
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools';
 
export const Route = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <TanStackRouterDevtools />
    </>
  ),
});

The <Outlet /> is where child routes render. During development, a devtools panel appears in the bottom corner. It won’t be included in your production build.

Shell Layout (AppBridge Provider)

First, create a frontend/src/appBridge.tsx file that initializes AppBridge once, exposes the bridge through React Context, and shows a loading state until the connection completes.

import {
	createContext,
	useContext,
	useEffect,
	useState,
	type ReactNode,
} from 'react';
import { createAppBridge, type AppBridge } from '@jtl-software/cloud-apps-core';

interface AppBridgeContextValue {
	appBridge: AppBridge | null;
}

const AppBridgeContext = createContext<AppBridgeContextValue>({
	appBridge: null,
});

export function useAppBridge() {
	return useContext(AppBridgeContext);
}

const bridgePromise = createAppBridge();

export function AppBridgeProvider({ children }: { children: ReactNode }) {
	const [appBridge, setAppBridge] = useState<AppBridge | null>(null);

	useEffect(() => {
		let cancelled = false;

		bridgePromise.then(bridge => {
			if (cancelled) return;
			setAppBridge(bridge);
		});

		return () => {
			cancelled = true;
		};
	}, []);

	if (!appBridge) {
		return (
			<div className='flex min-h-screen items-center justify-center'>
				<div className='text-center'>
					<div className='mx-auto size-8 animate-spin rounded-full border-4 border-gray-200 border-t-orange-500' />
					<p className='mt-4 text-sm text-gray-500'>
						Connecting to JTL Platform...
					</p>
				</div>
			</div>
		);
	}

	return (
		<AppBridgeContext.Provider value={{ appBridge }}>
			{children}
		</AppBridgeContext.Provider>
	);
}

Then, update the shell layout to wrap every iframe route.

frontend/src/routes/_shell.tsx:

import { createFileRoute, Outlet } from '@tanstack/react-router';
import { AppBridgeProvider } from '../appBridge';


function ShellLayout() {
	return (
		<AppBridgeProvider>
			<Outlet />
		</AppBridgeProvider>
	);
}

export const Route = createFileRoute('/_shell')({
	component: ShellLayout,
});

Setup Page

Add the following to your frontend/src/routes/_shell.setup.tsx:

import { createFileRoute } from '@tanstack/react-router';
import { Button, Box, Text } from '@jtl-software/platform-ui-react';
import { useAppBridge } from '../appBridge';
import { useEffect, useState } from 'react';

function SetupPage() {
	const { appBridge } = useAppBridge();
	const [tenantId, setTenantId] = useState<string | null>(null);
	const [isReady, setIsReady] = useState(false);
	const [error, setError] = useState<string | null>(null);

	useEffect(() => {
		if (!appBridge) return;
		let cancelled = false;

		async function init() {
			try {
				const { accessToken } = await appBridge.method.call<{
					accessToken: string;
				}>('getAppToken');
				if (cancelled) return;

				const res = await fetch('/api/connect-tenant', {
					headers: { Authorization: `Bearer ${accessToken}` },
				});
				if (cancelled) return;

				if (!res.ok) {
					const data = await res.json().catch(() => null);
					throw new Error(
						data?.error || `Connect failed (${res.status})`,
					);
				}

				const data = await res.json();
				if (cancelled) return;
				setTenantId(data.tenantId);
			} catch (err) {
				if (cancelled) return;
				setError(
					err instanceof Error ? err.message : 'Failed to initialize',
				);
			} finally {
				if (!cancelled) setIsReady(true);
			}
		}

		init();

		return () => {
			cancelled = true;
		};
	}, [appBridge]);

	const handleSetupCompleted = async () => {
		if (!appBridge) return;
		try {
			await appBridge.method.call('setupCompleted');
		} catch (err) {
			console.error('Setup completion failed:', err);
		}
	};

	if (!isReady) {
		return (
			<Box className='flex flex-col items-center justify-center min-h-screen gap-6'>
				<Text type='body' color='muted'>
					Linking your account...
				</Text>
			</Box>
		);
	}

	return (
		<Box className='flex flex-col items-center justify-center min-h-screen gap-6'>
			<Text type='h2' weight='bold' as='h1'>
				Connect to JTL Cloud
			</Text>
			<Box className='max-w-md text-center'>
				<Text
					type='body'
					color={error ? 'danger' : 'muted'}
					align='center'
				>
					{error || 'Your app has been verified and is ready to connect.'}
				</Text>
			</Box>
			{tenantId && (
				<Text type='small' color='muted'>
					Tenant:{' '}
					<code className='bg-gray-100 px-2 py-1 rounded'>
						{tenantId}
					</code>
				</Text>
			)}
			<Button
				onClick={handleSetupCompleted}
				label='Complete Setup'
				disabled={!!error}
			/>
		</Box>
	);
}

export const Route = createFileRoute('/_shell/setup')({
	component: SetupPage,
});

Uses the useAppBridge() hook to get the app token and send it to the /api/connect-tenant backend endpoint. The backend verifies the tenantId and completes the tenant connection. Once the app has successfully finished setup, call appBridge.method.call('setupCompleted') to mark the setup as complete.

If your app has additional setup steps, such as onboarding users, collecting merchant information, or completing internal checks, you can include those steps before calling setupCompleted.

ERP Page

Add the following to your frontend/src/routes/_shell.erp.tsx:

import { createFileRoute } from '@tanstack/react-router';
import { Box, Text } from '@jtl-software/platform-ui-react';

function ErpPage() {
	return (
		<Box className='p-8'>
			<Box className='mb-4'>
				<Text type='h2' weight='bold' as='h1'>
					My JTL Cloud App
				</Text>
			</Box>
			<Box className='mb-6'>
				<Text type='body' color='muted'>
					Your app is running inside the JTL Cloud.
				</Text>
			</Box>
		</Box>
	);
}

export const Route = createFileRoute('/_shell/erp')({
	component: ErpPage,
});

This is the page merchants see when they open your app from the Cloud ERP menu.

Hub Page

This route sits outside the shell layout and doesn’t inherit AppBridge initialization. When a merchant clicks the app card in the JTL Hub, this page opens in a full browser tab with no iframe and no app token.

frontend/src/routes/hub.tsx:

import { createFileRoute } from '@tanstack/react-router';
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  Text,
  Box,
  Button,
} from '@jtl-software/platform-ui-react';
import { ArrowUpRight } from 'lucide-react';
 
function HubPage() {
  return (
    <Box className="min-h-screen w-full flex items-center justify-center p-8">
      <Card className="max-w-[560px] w-full">
        <CardHeader className="items-center text-center gap-4 pt-10 pb-6">
          <CardTitle className="text-2xl font-semibold">Launched from JTL Cloud</CardTitle>
          <CardDescription className="text-center max-w-[420px]">
            This page opens in a full browser tab when a merchant clicks your app card
            in the JTL Hub. It runs outside the App Shell, so there is no AppBridge
            and no tenant context.
          </CardDescription>
        </CardHeader>
 
        <CardContent className="px-6 pb-6">
          <Box>
            <Text type="xs" weight="semibold" color="muted">Manifest mapping</Text>
            <Text type="inline-code">capabilities.hub.appLauncher.redirectUrl</Text>
          </Box>
        </CardContent>
 
        <CardFooter className="px-6 pb-8 pt-2">
          <a href="https://hub.jtl-cloud.com/" target="_blank" rel="noopener noreferrer">
            <Button
              variant="default"
              fullWidth
              label="Open JTL Cloud Hub"
              icon={<ArrowUpRight size={16} strokeWidth={2} />}
              iconPosition="right"
            />
          </a>
        </CardFooter>
      </Card>
    </Box>
  );
}
 
export const Route = createFileRoute('/hub')({
  component: HubPage,
});

6. Wire up the Router and Add AppBridgeProvider

Update frontend/src/main.tsx to initialize the router and render the layout and routes.

import ReactDOM from 'react-dom/client';
import { RouterProvider, createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';
import './index.css';

const router = createRouter({ routeTree });

declare module '@tanstack/react-router' {
	interface Register {
		router: typeof router;
	}
}

const rootElement = document.getElementById('root')!;
if (!rootElement.innerHTML) {
	ReactDOM.createRoot(rootElement).render(<RouterProvider router={router} />);
}

7. Run the Frontend

Start the dev server:

npm run dev

The first time you run this, the TanStack Router plugin generates src/routeTree.gen.ts automatically.

Visit each route to confirm the app works:

1. Visit http://localhost:5173/setup

   You should see a spinner and then a message: “Connecting to JTL Platform…”. This shows the routing works and the shell layout mounts, AppBridge attempts to initialize, and fails (no backend yet).

2. Visit http://localhost:5173/erp

   Same waiting message as before. Confirms the second iframe route loads and reuses the shell layout.

3. Visit http://localhost:5173/hub

   You should see the “Launched from JTL Cloud” card. No spinner, no error, since this route bypasses the shell layout entirely.

Common Issues

'window is not defined' or 'AppBridge is not defined'

This app is a client-only Vite build with no server render, so a top-level import is safe. Make sure you are running npm run dev rather than building for a server environment.

If you are adapting this setup for a framework with server-side rendering, load the SDK with a dynamic await import('@jtl-software/cloud-apps-core') inside a client-side provider instead.

'Cannot find module ./routeTree.gen' in main.tsx

This means the route tree file has not been generated yet. It is created automatically by the TanStack Router Vite plugin when it detects your route files.

Start the dev server with npm run dev, then save any file inside src/routes/. The plugin watches this folder and will generate src/routeTree.gen.ts as soon as it detects a change.

If the file still does not appear, check vite.config.ts. The tanstackRouter() plugin must be listed before react() in the plugins array.

Routes resolve to /_shell/setup instead of /setup

This usually means the route is not being treated as a pathless layout.

In TanStack Router, the leading underscore (_) marks a route as pathless. If the file is named shell.setup.tsx (without the underscore), _shell becomes part of the URL.

Rename the file to _shell.setup.tsx to restore the expected behavior. Also make sure you are using the flat-file convention (_shell.setup.tsx), not a folder structure like _shell/setup.tsx, since this guide assumes the flat-file format.

useAppBridge() returns null inside a child route, even after the spinner finishes

This usually happens when AppBridgeContext and useAppBridge are defined in the same file as a TanStack Router route (for example, _shell.tsx).

During development, the router’s Vite integration can create multiple module instances under hot module replacement (HMR). This causes the provider and consumer to reference different context objects, so useAppBridge() returns null.

Fix: Move the context, hook, and provider into a separate file (for example, src/appBridge.tsx) and import useAppBridge from there in all components.

Next: Build the Backend

Pick a language to build the backend that will verify app tokens and proxy requests to the JTL API:

Node.js

Express and TypeScript.

C# (.NET)

ASP.NET Core 8.

PHP

Slim 4 and PHP.