This is the legacy documentation of Project-level Custom Applications, which is in maintenance mode. Visit the new documentation for Org-level Custom Applications.

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

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 application runtime environment, which is exposed 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. See also `children` to opt-into the new behavior to simplify the setup. The `render` prop still continues to be supported.
`children`	`node`	✅ (*)	-	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.
`trackingEventList`	`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>