@/application-shell

Installation

yarn add @commercetools-frontend/application-shell

# or

npm --save install @commercetools-frontend/application-shell

Additionally install the peer dependencies (if not present)

yarn add @apollo/client react react-dom react-intl react-redux react-router-dom redux @testing-library/react @testing-library/react-hooks

# or

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.
The ApplicationShell component is expected to be rendered as the top-level component of your application.

Usage

We recommend to 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.

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

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

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

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

Properties

ApplicationPageTitle

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.

Properties

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.

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

setupGlobalErrorListener();

const EntryPoint = () => {
  return (
    <ApplicationShell
      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:

• cache (optional): Configuration of the Apollo cache in relation to the data requirements of your Custom Application.

• restLink (optional): Instance of the Apollo REST link.

  This feature is available from version 21.10.0 onwards.

  The apollo-link-rest and its related dependencies are not included in the @commercetools-frontend/application-shell package and must be installed separately.

  When configuring the REST link, we recommend setting the uri using the getMcApiUrl() utility function.

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.

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 <ApplicationShell>.

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

const apolloClient = configureApolloClient();

const EntryPoint = () => {
  return (
    <ApplicationShell
      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.

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

renderAppWithRedux({
  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.

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

const useExternalApiFetcher = () => {
  // Assuming that the `custom-application-config.json` 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,
  }
};

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 configuring the audience policy.
• includeUserPermissions (optional): See configuring custom claims.
• version (optional): See versioning.

executeHttpClientRequest

This function should be used for configuring custom HTTP clients to provide all the recommended functionalities such as:

• Defining the required/recommended HTTP headers for the Merchant Center API.
• Automatically renewing the token to access a particular API.

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 configuring the audience policy.
  • includeUserPermissions (optional): See configuring custom claims.
  • version (recommended): See versioning.

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

• Example using Fetch
• Example using Axios
• Example using Stale-While-Revalidate (SWR)
• Example using Ky

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 Custom Applications.

import { /**/ } from '@commercetools-frontend/application-shell/test-utils';

Most of the utility functions related to React Testing Library, as the recommended testing approach. See Testing for more information.

In general the test-utils simulate the components-under-test as if it was rendered by the <ApplicationShell> and provide the necessary setup to fully test a Custom Application. This includes things like Apollo, React Intl, React Router, etc.

renderApp

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

Return values

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

renderAppWithRedux

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

mapResourceAccessToAppliedPermissions

Helper function to map user permissions to applied resource permissions. This is useful in testing when defining user permissions. See Testing user permissions for more information.

{
  project: {
    allAppliedPermissions: mapResourceAccessToAppliedPermissions([
      PERMISSIONS.ViewAvengers,
    ]),
  },
}

denormalizePermissions

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

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