BETA

Application Shell

Description

The <ApplicationShell> is a React component that ties together all the main functionalities of the Custom Applications.

The React component is available from the @commercetools-frontend/application-shell package and is meant to be used as the top-level component of the React application.

Usage

import {
ApplicationShell,
setupGlobalErrorListener,
} from '@commercetools-frontend/application-shell';
const loadMessages = (locale) => {
// ...
}
const entryPointUriPath = 'examples-starter'
const AsyncApplicationRoutes = React.lazy(
() => import('../../routes' /* webpackChunkName: "starter-routes" */)
);
export const ApplicationStarter = () => (
<Switch>
<Route
path={`/:projectKey/${entryPointUriPath}`}
component={AsyncApplicationRoutes}
/>
<RouteCatchAll />
</Switch>
);
ApplicationStarter.displayName = 'ApplicationStarter';
setupGlobalErrorListener();
const EntryPoint = () => (
<ApplicationShell
environment={window.app}
applicationMessages={loadMessages}
onRegisterErrorListeners={() => {/* noop */}}
DEV_ONLY__loadNavbarMenuConfig={() =>
import('./menu.json').then(data => data.default || data)
}
render={() => (<ApplicationStarter />)}
/>
)

From version >= 17.8.0 there is a new opt-in behavior to simplify the entry point setup, where the main application route is pre-configured within the <ApplicationShell>. To opt-into this behavior, simply render your application component as children of <ApplicationShell> instead of using the render prop.

import {
ApplicationShell,
setupGlobalErrorListener,
} from '@commercetools-frontend/application-shell';
const loadMessages = (locale) => {
// ...
}
const AsyncApplicationRoutes = React.lazy(
() => import('../../routes' /* webpackChunkName: "starter-routes" */)
);
setupGlobalErrorListener();
const EntryPoint = () => (
<ApplicationShell
environment={window.app}
applicationMessages={loadMessages}
onRegisterErrorListeners={() => {/* noop */}}
DEV_ONLY__loadNavbarMenuConfig={() =>
import('./menu.json').then(data => data.default || data)
}
>
<AsyncApplicationRoutes />
</ApplicationShell>
)

The render prop is still supported but it's recommended to use the children prop and the implicit setup. This is important as the custom-application-config.json becomes more the single source of truth.

Properties

PropsTypeRequiredDefaultDescription
applicationMessagesobject or func-This is either an object containing all the translated messages, grouped by locale ({ "en": { "Welcome": "Welcome" }, "de": { "Welcome": "Wilkommen" }}), or a function that returns a Promise that resolves to such an object. The function is called with a locale parameter. See Using the messages in the application.
environmentobject-The application runtime environment, which is exposed in window.app. See Runtime configuration.
renderfunc✅ (*)-The render function is called when the <ApplicationShell> is ready to render the actual application. This is the case when the required data (user, project) has been fetched and the application context has been initialized. See also children to opt-into the new behavior to simplify the setup. The render prop still continues to be supported.
childrennode✅ (*)-Instead of using the render prop, render your application component as children of <ApplicationShell>. By doing so, the <ApplicationShell> pre-configures the main application routes according to the entryPointUriPath defined in the custom-application-config.json. This is an opt-int behavior as a replacement of the render prop, to simplify the entry point setup.
trackingEventListobject-An optional object containing a map of tracking events.
onRegisterErrorListenersfunc-A callback function to set up global event listeners, executed once when the <ApplicationShell> is mounted. The function is called with the following named arguments: dispatch (the dispatch function of Redux). See About onRegisterErrorListeners.
onMenuItemClickfunc--A callback function that is called when the user clicks on the menu items. The function is called with the following arguments: event (the DOM event) and track (the GTM tracking function). You can extract from the event.currentTarget all the useful information about the link.
DEV_ONLY__loadNavbarMenuConfigfunc✅ (development only)-A function that returns a Promise to load the menu.json config for the navigation component on the left side (see warning below).
DEV_ONLY__loadAppbarMenuConfigfunc✅ (development only)-A function that returns a Promise to load the menu.json config for the account links in the application bar component on the top (see warning below).

The DEV_ONLY_ properties are only used in development mode. See Links for local development. It's recommended to load the menu.json using a dynamic import to enable Code-Splitting.

About onRegisterErrorListeners

This callback function allows to set up global error listeners. For now, the main use case is to implement the error handler of the sdk package.

import { Sdk } from '@commercetools-frontend/sdk';
import { handleActionError } from '@commercetools-frontend/actions-global';
const onRegisterErrorListeners = ({ dispatch }) => {
Sdk.Get.errorHandler = error =>
handleActionError(error, 'sdk')(dispatch);
}

Test utils

See Test utils for <ApplicationShell>

Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2021 commercetools
Privacy PolicyImprint