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) => {
  // ...
}
setupGlobalErrorListener();
const EntryPoint = () => (
  <ApplicationShell
    environment={window.app}
    applicationMessages={loadMessages}
    onRegisterErrorListeners={() => {/* noop */}}
    DEV_ONLY__loadNavbarMenuConfig={() =>
      import('./menu.json').then(data => data.default || data)
    }
    render={() => (<MyApplication />)}
  />
)

Properties

Props	Type	Required	Default	Description
`applicationMessages`	`object` 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.
`environment`	`object`	✅	-	The object containing the `env.json`. By default this is available in `window.app`. See Runtime configuration.
`render`	`func`	✅	-	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.
`trackingEventWhitelist`	`object`		-	An optional object containing a map of tracking events.
`onRegisterErrorListeners`	`func`	✅	-	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`.
`onMenuItemClick`	`func`	-	-	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__loadNavbarMenuConfig`	`func`	✅ (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__loadAppbarMenuConfig`	`func`	✅ (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>