Documentation

Application Shell

Elevate, May 20-22-2025, Miami Beach, Florida

Set of components and utilities to serve as the customization framework.

Installation

Install the @commercetools-frontend/application-shell package
npm --save install @commercetools-frontend/application-shell

Additionally, install the peer dependencies (if not present)

npm --save install @apollo/client react react-dom react-intl react-redux react-router-dom redux @testing-library/react @testing-library/react-hooks

Components

ApplicationShell

This is the main component that contains all the general logic to render a Custom Application.

This component applies only to Custom Applications. If you're developing a Custom View, use CustomViewShell instead.
The ApplicationShell component is expected to be rendered as the top-level component of your application.

Usage

We recommend that you render the application content as children of <ApplicationShell> instead of the render prop.
This allows the <ApplicationShell> to pre-configure the application entry point routes. In addition to that, the entry point route is protected by the basic View permission check. This means that a user without permissions of your Custom Application won't be able to access the Custom Application route.
entry-point.jsjsx
import { ApplicationShell } from '@commercetools-frontend/application-shell';

const loadMessages = async (locale) => {
  // ...
};

const AsyncApplicationRoutes = React.lazy(() =>
  import('../../routes' /* webpackChunkName: "channels" */)
);

const EntryPoint = () => (
  <ApplicationShell environment={window.app} applicationMessages={loadMessages}>
    <AsyncApplicationRoutes />
  </ApplicationShell>
);
export default EntryPoint;

Properties

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 Import translations.

environment

object
The application runtime environment, which is exposed in window.app. See Runtime configuration.

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.

render

func (optional)
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.
It's recommended to use the children prop to benefit from a simpler setup.

apolloClient

ApolloClient (optional)
An optional instance of ApolloClient to be used instead of the default one. This is usually the case when you need to configure the Apollo cache. See createApolloClient.

CustomViewShell

This component applies only to Custom Views. If you're developing a Custom Application, use ApplicationShell instead.
This is the main component that contains all the general logic to render a Custom View. The CustomViewShell component must be rendered as the top-level component of your Custom View.

Usage

We recommend that you render the Custom View content as children of <CustomViewShell>.
The <CustomViewShell> pre-configures the Custom View entry point routes. In addition, the entry point route is protected by the basic View permission check. This means that a user without permission from your Custom View won't be able to access the Custom View route.

You aren't required to use routes in your Custom View. You can use them if you need to have different views. For example, a Custom View with a listing page and details page.

entry-point.jsjsx
import { CustomViewShell } from '@commercetools-frontend/application-shell';

const loadMessages = async (locale) => {
  // ...
};

const AsyncApplicationRoutes = React.lazy(() =>
  import('../../routes' /* webpackChunkName: "channels" */)
);

const EntryPoint = () => (
  <CustomViewShell applicationMessages={loadMessages}>
    <AsyncApplicationRoutes />
  </CustomViewShell>
);
export default EntryPoint;

Properties

applicationMessages

object or func
This is either an object containing all the translated messages, grouped by locale
{ en: { Welcome: "Welcome" }, de: { Welcome: "Willkommen" } }
or a function that returns a Promise that resolves to such an object.
The function is called with a locale parameter. See Import translations.

children

node
Instead of using the render prop, render your application component as children of <CustomViewShell>.
By doing so, the <CustomViewShell> 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.

apolloClient

ApolloClient (optional)
An optional instance of ApolloClient to be used instead of the default one. This is usually the case when you need to configure the Apollo cache. See createApolloClient.

ApplicationPageTitle

This component applies only to Custom Applications and is available from version 21.15.0 onwards.
Use this component to overwrite the document's default <title>.

Usage

We recommend using this component on pages with a human-readable resource identifier, for example, a Product name on the product details page.

import { ApplicationPageTitle } from '@commercetools-frontend/application-shell';

<ApplicationPageTitle additionalParts={['Red shoes']} />;
// Red shoes - products - my-shop - Merchant Center
When the <ApplicationPageTitle> component is used multiple times, the last one rendered will overwrite the previous ones.
Refer to the Mapping guidelines to understand when to overwrite the title and when not.

Properties

additionalParts

string[]
A list of parts to be prepended to the default page title, separated by -.

Hooks

useMcQuery

A React hook that wraps the useQuery hook of Apollo Client. The only difference is that useMcQuery properly types the context object, which is always used to define the GraphQL target. See Data fetching.

useMcLazyQuery

A React hook that wraps the useLazyQuery hook of Apollo Client. The only difference is that useMcLazyQuery properly types the context object, which is always used to define the GraphQL target. See Data fetching.

useMcMutation

A React hook that wraps the useMutation hook of Apollo Client. The only difference is that useMcMutation properly types the context object, which is always used to define the GraphQL target. See Data fetching.

Utilities

setupGlobalErrorListener

Configures global event listeners to catch unexpected errors and report them to Sentry. Make sure to render this in the entry-point file.

For Custom Applications

For Custom Views

entry-point.jsJavascript
import {
  setupGlobalErrorListener,
  ApplicationShell,
} from '@commercetools-frontend/application-shell';

setupGlobalErrorListener();

const EntryPoint = () => {
  return (
    <ApplicationShell
      apolloClient={apolloClient}
      // ...other props
    />
  );
};
entry-point.jsJavascript
import {
  setupGlobalErrorListener,
  CustomViewShell,
} from '@commercetools-frontend/application-shell';

setupGlobalErrorListener();

const EntryPoint = () => {
  return (
    <CustomViewShell
      apolloClient={apolloClient}
      // ...other props
    />
  );
};

createApolloClient

Creates a new instance of the Apollo Client. Use this to extend certain functionalities of the preconfigured Apollo Client.

import { createApolloClient } from '@commercetools-frontend/application-shell';

createApolloClient({
  // ...
});

Available options are:

To allow reusing the custom Apollo Client instance in different places, we recommend creating a separate file, for example src/apollo-client.js, and define the configuration there.
apollo-client.jsJavascript
import { createApolloClient } from '@commercetools-frontend/application-shell';

const configureApollo = () =>
  createApolloClient({
    cache: {
      // ...
    },
  });

export default configureApollo;
The new Apollo Client instance must be explicitly passed to the either the <ApplicationShell> or <CustomViewShell>.

For Custom Applications

For Custom Views

entry-point.jsJavascript
import { ApplicationShell } from '@commercetools-frontend/application-shell';
import configureApolloClient from '../../apollo-client';

const apolloClient = configureApolloClient();

const EntryPoint = () => {
  return (
    <ApplicationShell
      apolloClient={apolloClient}
      // ...other props
    />
  );
};
entry-point.jsJavascript
import { CustomViewShell } from '@commercetools-frontend/application-shell';
import configureApolloClient from '../../apollo-client';

const apolloClient = configureApolloClient();

const EntryPoint = () => {
  return (
    <CustomViewShell
      apolloClient={apolloClient}
      // ...other props
    />
  );
};

Furthermore, in your tests you also need to create a new instance of your custom Apollo Client and pass it to the test utils.

For Custom Applications

For Custom Views

import { renderAppWithRedux } from '@commercetools-frontend/application-shell/test-utils';
import configureApolloClient from '../../apollo-client';

renderAppWithRedux({
  apolloClient: configureApolloClient(),
  // ...
});

import { renderCustomView } from '@commercetools-frontend/application-shell/test-utils';
import configureApolloClient from '../../apollo-client';

renderCustomView({
  apolloClient: configureApolloClient(),
  // ...
});

createApolloContextForProxyForwardTo

Creates the Apollo context object with all the required options for using the /forward-to endpoint. See Integrate with your own API.

For Custom Applications

For Custom Views

import {
  createApolloContextForProxyForwardTo,
  useMcQuery,
} from '@commercetools-frontend/application-shell';
import { useApplicationContext } from '@commercetools-frontend/application-shell-connectors';

const useExternalApiFetcher = () => {
  // Assuming that the `custom-application-config` file contains the custom value:
  // `{ additionalEnv: { externalApiUrl: 'https://my-custom-app.com/graphql'} }`
  const externalApiUrl = useApplicationContext(
    (context) => context.environment.externalApiUrl
  );
  const { loading, data, error } = useMcQuery(MyQuery, {
    context: createApolloContextForProxyForwardTo({
      // The URL to your external API
      uri: externalApiUrl,
      // Provide custom HTTP headers (optional)
      headers: {
        'x-foo': 'bar',
      },
      // Set `"X-Forward-To-Audience-Policy"` header in the request with provided value (optional)
      audiencePolicy: 'forward-url-full-path',
      // Set `"X-Forward-To-Claims": "permissions"` header in the request (optional)
      includeUserPermissions: true,
    }),
  });

  return {
    loading,
    data,
    error,
  };
};

import {
  createApolloContextForProxyForwardTo,
  useMcQuery,
} from '@commercetools-frontend/application-shell';
import { useCustomViewContext } from '@commercetools-frontend/application-shell-connectors';

const useExternalApiFetcher = () => {
  // Assuming that the `custom-view-config` file contains the custom value:
  // `{ additionalEnv: { externalApiUrl: 'https://my-custom-view.com/graphql'} }`
  const externalApiUrl = useCustomViewContext(
    (context) => context.environment.externalApiUrl
  );
  const { loading, data, error } = useMcQuery(MyQuery, {
    context: createApolloContextForProxyForwardTo({
      // The URL to your external API
      uri: externalApiUrl,
      // Provide custom HTTP headers (optional)
      headers: {
        'x-foo': 'bar',
      },
      // Set `"X-Forward-To-Audience-Policy"` header in the request with provided value (optional)
      audiencePolicy: 'forward-url-full-path',
      // Set `"X-Forward-To-Claims": "permissions"` header in the request (optional)
      includeUserPermissions: true,
    }),
  });

  return {
    loading,
    data,
    error,
  };
};

Available options are:

  • uri (required): The URL of the external API to forward the request to.
  • headers (optional): Additional HTTP headers to be included in the request to the external API.
  • audiencePolicy (optional): See configure the audience policy.
  • includeUserPermissions (optional): See configure custom claims.
  • version (optional): See versioning.

executeHttpClientRequest

This feature is available from version 21.10.0 onwards.
This function should be used for configuring custom HTTP clients to provide all the recommended functionalities such as:
import { executeHttpClientRequest } from '@commercetools-frontend/application-shell';
The function accepts a callback function THttpClientFetcher to execute the request and an optional object THttpClientConfig for the HTTP request configuration.
The callback function THttpClientFetcher is passed one argument with the configured request options THttpClientOptions that you would use to configure the HTTP request for your HTTP client.
type THttpClientOptions = {
  credentials: 'include';

  /**
   * The HTTP headers included by default are:
   * - Accept
   * - Authorization (only in development)
   * - X-Application-Id
   * - X-Correlation-Id
   * - X-Project-Key
   * - X-User-Agent
   */
  headers: THeaders;
};
type TFetcherResponse<Data> = {
  /**
   * The parsed response from the server.
   */
  data: Data;
  /**
   * The HTTP status code from the server response.
   */
  statusCode: number;
  /**
   * Implement a function to access the HTTP headers from the server response.
   */
  getHeader: (headerName: string) => string | null;
};
type THttpClientFetcher<Data> = (
  options: THttpClientOptions
) => Promise<THttpClientFetcherResponse<Data>>;

async function executeHttpClientRequest<Data>(
  fetcher: THttpClientFetcher<Data>,
  config?: THttpClientConfig
): Promise<Data>;
The THttpClientConfig object accepts the following options:
  • userAgent (optional): A custom user agent to identify the HTTP client.
    We recommend to use the @commercetools/http-user-agent package.
    import createHttpUserAgent from '@commercetools/http-user-agent';

const userAgent = createHttpUserAgent({
  name: 'fetch-client',
  version: '2.6.0',
  libraryName: window.app.applicationName,
  contactEmail: 'support@my-company.com',
});
  • headers (optional): Additional HTTP headers to be included in the request. The provided recommended headers won't be overwritten.
  • forwardToConfig (optional): Configuration for using the /proxy/forward-to endpoint to connect to an external API.
    • uri (required): The URL of the external API to forward the request to.
    • headers (optional): Additional HTTP headers to be included in the request to the external API.
    • audiencePolicy (optional): See configure the audience policy.
    • includeUserPermissions (optional): See configure custom claims.
    • version (recommended): See versioning.

You can see some examples of integrating this with different HTTP clients:

getMcApiUrl

Returns the URL of the Merchant Center API. This is useful to configure HTTP clients that should connect to that API.
import { getMcApiUrl } from '@commercetools-frontend/application-shell';

const mcApiUrl = getMcApiUrl();
// https://mc-api.<region>.commercetools.com

buildApiUrl

Returns a URL of the Merchant Center API for the given URI path. This is useful to configure the request URL without having to get the URL of the Merchant Center API.
import { buildApiUrl } from '@commercetools-frontend/application-shell';

const apiEndpoint = buildApiUrl('/proxy/ctp/channels');
// https://mc-api.<region>.commercetools.com/proxy/ctp/channels

Test utils

The package provides a separate entry point with utilities for testing customizations.

import /**/ '@commercetools-frontend/application-shell/test-utils';
Most of the utility functions related to React Testing Library, as the recommended testing approach. For more information, see Testing.
In general, the test-utils simulate the components-under-test as if it was rendered by the <ApplicationShell> or <CustomViewShell> and provide the necessary setup to fully test a customization. This includes things like Apollo, React Intl, React Router, etc.

renderApp

This component applies only to Custom Applications. If you're developing a Custom View, see renderCustomView.
A wrapper around the render method of React Testing Library. All the basic setup for testing is included here.

Usage

import {
  renderApp,
  screen,
} from '@commercetools-frontend/application-shell/test-utils';

describe('rendering', () => {
  it('should render the authenticated users first name', async () => {
    renderApp(<FirstName />, {
      user: {
        firstName: 'Leonard',
      },
    });
    await screen.findByText('First name: Leonard');
  });
});

Options

locale

string
Determines the UI language and number format. Is used to configure <IntlProvider>. Only core messages will be available during tests, no matter the locale. The locale can be a full IETF language tag, although the Merchant Center is currently only available in a limited set of languages.

dataLocale

string
Sets the locale which is used to display LocalizedStrings.

mocks

mock[]
Allows mocking requests made with Apollo. mocks is forwarded as the mocks argument to MockedProvider. If mocks is not provided or is an empty array, the Apollo MockedProvider is not used. This is an opt-in functionality, as the default behavior is to mock requests using Mock Service Worker.

apolloClient

ApolloClient
Pass a custom instance of Apollo client, useful when your Custom Application has some custom cache policies. You can use the exported function createApolloClient of @commercetools-frontend/application-shell.

route

string
The route the user is on, like /test-project/products. Defaults to /.

disableAutomaticEntryPointRoutes

boolean
Pass true if you are using the render prop for the <ApplicationShell> instead of the children prop.

history

object
By default a memory-history is generated which has the provided route set as its initial history entry. It's possible to pass a custom history as well. In that case, we recommend using the factory function createEnhancedHistory from the @commercetools-frontend/browser-history package, as it contains the enhanced location with the parsed query object.

adapter

object
The FlopFlip adapter to use when configuring flopflip. Defaults to memoryAdapter.

flags

object
An object whose keys are feature-toggle keys and whose values are their toggle state. Use this to test your component with different feature toggle combinations. Example: { betaUserProfile: true }.

environment

object
Allows to set the applicationContext.environment. The passed object gets merged with the tests default environment. Pass null to completely remove the environment, which renders the ui as if no environment was given.

user

object
Allows to set the applicationContext.user. The passed object gets merged with the test's default user. Pass null to completely remove the user, which renders the ui as if no user was authenticated.

project

object
Allows to set the applicationContext.project. The passed object gets merged with the tests default project. Pass null to completely remove the project which renders the ui outside of a project context.

Return values

Calling renderApp returns the same Result object of React Testing Library, with the addition of the following properties:

history

object
The history created by renderApp which is passed to the router. It can be used to simulate location changes and so on.

user

object
The user object used to configure <ApplicationContextProvider>, so the result of merging the default user with options.user. Note that this is not the same as applicationContext.user. Can be undefined when no user is authenticated (when options.user was null).

project

object
The project object used to configure <ApplicationContextProvider>, so the result of merging the default project with options.project. Note that this is not the same as applicationContext.project. Can be undefined when no project was set (when options.project was null).

environment

object
The environment object used to configure <ApplicationContextProvider>, so the result of merging the default environment with options.environment. Note that this is not the same as applicationContext.environment. Can be undefined when no environment was set (when options.environment was null).

renderAppWithRedux

This component applies only to Custom Applications. If you're developing a Custom View, see renderCustomView.
A wrapper around the renderApp method with the additional support of Redux. This is only useful if your components-under-test relies on Redux, for example when dispatching notifications.

Usage

import {
  renderAppWithRedux,
  screen,
} from '@commercetools-frontend/application-shell/test-utils';

describe('rendering', () => {
  it('should render the authenticated users first name', async () => {
    renderAppWithRedux(<FirstName />, {
      user: {
        firstName: 'Leonard',
      },
    });
    await screen.findByText('First name: Leonard');
  });
});

Options

In addition to the following options, the method accepts all options from renderApp. It is not possible to pass either storeState or sdkMocks together with store.

store

object
A custom redux store.

storeState

object
Pass an initial state to the default Redux store.

sdkMocks

mock[]
Allows mocking requests made with @commercetools-frontend/sdk (Redux). The sdkMocks is forwarded as mocks to the SDK test-utils.

renderCustomView

This component applies only to Custom Views. If you're developing a Custom Application, see renderApp or renderAppWithRedux.
A wrapper around the render method of the React Testing Library. All the basic setup for testing is included here.

Usage

import {
  renderCustomView,
  screen,
} from '@commercetools-frontend/application-shell/test-utils';

describe('rendering', () => {
  it('should render the authenticated users first name', async () => {
    renderCustomView({
      user: {
        firstName: 'Leonard',
      },
      children: <FirstName />,
    });
    await screen.findByText('First name: Leonard');
  });
});

Options

locale

string
Determines the UI language and number format. It is used to configure <IntlProvider>. Only core messages will be available during tests, no matter the locale. The locale can be a full IETF language tag, although the Merchant Center is currently only available in a limited set of languages.

projectKey

string
Sets the Custom View context projectKey. The passed key gets merged with the tests default project.

projectAllAppliedPermissions

string
Sets the default project allAppliedPermissions property. The passed array will replace the default project allAppliedPermissions.

customViewHostUrl

string
Defines the URL the Custom View receives as part of the emulation of it being rendered in a Merchant Center built-in application.

customViewConfig

string
The configuration object used to configure the <CustomViewContextProvider>, so the result of merging the default Custom View configuration with options.customViewConfig.

apolloClient

ApolloClient
Pass a custom instance of Apollo client, useful when your Custom View has some custom cache policies. You can use the exported function createApolloClient of @commercetools-frontend/application-shell.

environment

object
Sets the customViewContext.environment. The passed object gets merged with the tests default environment. Pass null to completely remove the environment, which renders the ui as if no environment was given.

user

object
Sets the customViewContext.user. The passed object gets merged with the test's default user. Pass null to completely remove the user, which renders the ui as if no user was authenticated.

Return values

Calling renderCustomView returns the Result object of React Testing Library, with the addition of the following properties:

history

object
The history created by renderApp which is passed to the router. It can be used to simulate location changes and so on.

user

object
The user object used to configure <CustomViewContextProvider>, so the result of merging the default user with options.user. Note that this is not the same as customViewContext.user. Can be undefined when no user is authenticated (when options.user was null).

project

object
The project object used to configure <CustomViewContextProvider>, so the result of merging the default project with options.project. Note that this is not the same as customViewContext.project. Can be undefined when no project was set (when options.project was null).

environment

object
The environment object used to configure <CustomViewContextProvider>, so the result of merging the default environment with options.environment. Note that this is not the same as customViewContext.environment. Can be undefined when no environment was set (when options.environment was null).

mapNotificationToComponent

func
Pass a function to map a notification to a custom component.

mapResourceAccessToAppliedPermissions

Helper function to map user permissions to applied resource permissions. This is useful in testing when defining user permissions. For more information, see Test user permissions.
{
  project: {
    allAppliedPermissions: mapResourceAccessToAppliedPermissions([
      PERMISSIONS.View,
    ]),
  },
}

denormalizePermissions

Helper function to map user permissions defined as objects to a list of applied resource permissions.

{
  project: {
    allAppliedPermissions: denormalizePermissions({
      canViewCustomChannels: true,
    }),
  },
}