Merchant Center Customizations Releases

This guide provides detailed information about the migration process and necessary changes for Custom Applications and Custom Views to ensure a successful migration.

Each customization type provides unique possibilities for adding custom functionality, as well as offering different user experiences within the Merchant Center.

• With Custom Views, you can add custom functionality in the context of a specific page within a built-in Merchant Center application.

• With Custom Applications, you can add new applications with custom functionality to the Merchant Center main menu.

Developing Custom Views is similar to developing Custom Applications because they share many of the same concepts and resources. If you have experience developing Custom Applications, you can use this knowledge to build Custom Views.

The new main navigation menu brings a fresh look and enhanced functionality to help you navigate your application effortlessly. It provides a smoother and intuitive user experience in the Merchant Center.

This enhancement allows you to make changes to permission, for example, adding new OAuth Scopes, managing permission groups, or removing unused scopes, all without uninstalling the application. With this update, all existing team permissions remain unaffected.

This release contains breaking changes.

This release contains some major dependency version updates. We don't expect any migration steps necessary aside some minor test adjustments (see migration steps below).

The following libraries have been updated to new major versions:

• @commercetools-frontend/ui-kit and all @commercetools-uikit/* packages have been updated to v16.
• react-intl and @formatjs/cli have been updated to v6.
• jest and @types/jest have been updated to v29.
• jsdom has been updated to v21.
• eslint-plugin-jest has been updated to v27.

{/* <!-- more */}

Upgrading peer dependencies

Make sure to upgrade the following dependencies:

• react-intl and @formatjs/cli to v6
• jest and @types/jest to v29
• jest-runner-eslint to v2
• jest-watch-typeahead to v2

Migrating Jest

We don't expect any specific migration effort besides updating all Jest dependencies to their latest version (including possible Jest plugins being used).

However, there are a couple of possible necessary updates to consider:

• Jest snapshots format changed a bit. You might need to update your snapshots by passing the option -u to the Jest command.
• The ESLint plugin for Jest might yield some new errors due to its breaking changes. See changelog.

For more detailed information about upgrading Jest, please refer to the official guides:

• From v27 to v28
• From v28 to v29

{/* <!-- more */}

• Default size: big.
• Available sizes: medium, big.
• Changes: Replaced the small size with medium for consistency. The small size will continue to work until the deprecation notice.

• Default size: big.
• Available sizes: medium, big.
• Changes: Added the medium size.

• Default size: big.
• Available sizes: small, medium, big.
• Changes: No changes.

• Default size: big.
• Available sizes: small, medium, and big.
• Changes: Added two new size options—small and medium.

If you're using the legacy workaround of creating multiple Custom Applications with different entry points, we recommend migrating to deployment previews. They provide a better developer experience with less maintenance since you only need to configure one Custom Application.

Up until now, this functionality was limited to installing a Custom Application in the same Organization where it was configured. This limitation was mainly posed to reduce the scope of the initial release.

As of today, we are happy to announce that Custom Applications can be installed in other Organizations where the user has administration rights.

This gives users a bit more time to finish the migration from Project-level Custom Applications.

This release includes several new features that we would like to present:

• Official support for developing Custom Applications in TypeScript, including a new starter template. Read more about TypeScript in the Adding TypeScript page.
• New policy option for configuring the audience field when integrating your Custom Application with an external API.
• Improved accessibility of different elements using ARIA attributes.
• Simpler and more readable list of time zone data, available from the @commercetools-frontend/l10n package.
• New React hook useProjectExtensionImageRegex for accessing the project images configuration, available from the @commercetools-frontend/application-shell-connectors package.

{/* <!-- more */}

Deprecations

After collecting feedback during the beta phase, and with the recent milestone of migrating Custom Applications to Org-level, we now have a solid foundation on the functionalities and developer tooling for Custom Applications.

This release includes several new features that we would like to present:

• A new built-in Stacking Layer System to automatically and consistently calculate z-index values of stacked modal containers.
• New layout UI components <InfoDetailPage>, <FormDetailPage> and <CustomFormDetailPage>.
• The CLI commands config:sync now lists changes when updating an existing Custom Application configuration.
• The Jest preset @commercetools-backend/jest-preset-mc-app contains more Intl polyfills.

{/* <!-- more */}

Background

Stacking Layer System

This release includes several new features that we would like to present:

• New CLI commands login and config:sync to help maintaining Custom Applications.
• New layout UI components <TabularMainPage> and <TabularDetailPage>. In addition to that, a new <TabHeader> component is exported from the @commercetools-frontend/application-components package to be used in the tabular UI components <TabularModalPage>, <TabularMainPage> and <TabularDetailPage>.
• New ESLint config @commercetools-backend/eslint-config-node for Node.js projects with built-in TypeScript support.
• The notification components now support the aria role alertdialog and the aria-describedby attributes. This helps in particular to write more specific and relevant selector in tests.

This release contains breaking changes.

This version marks the release of new Custom Application features.

Furthermore, the Custom Application documentation has been restructured and updated to match the new status quo of Custom Applications. The Project-level legacy documentation remains available during the migration period in a separate location.

Follow the steps below to migrate your Application Kit packages to the new version.

{/* <!-- more */}

New documentation

The Custom Applications documentation has been restructured and improved to provide a better developer experience. During the migration period the Project-level legacy documentation remains available for maintenance and reference purposes.

Supported Node.js versions

Upgrading ESLint to v8

The upgrade might include some rule changes and therefore some lint errors that need to be fixed.

Changes to peer dependencies

The following packages have updated their peer dependencies requirements:

• @commercetools-frontend/application-shell: requires @testing-library/react version 12.x and @testing-library/react-hooks version 7.x.
• @commercetools-frontend/cypress: requires cypress version 8.x || 9.x.
• @commercetools-frontend/jest-stylelint-runner: requires stylelint version 14.x.

Changes to Custom Application config

The Custom Application config file has some new required fields.

• env.development
• oAuthScopes
• *.defaultLabel

In addition to that, the menu link structure also changed a bit.

Referencing constants

Migrating from menu.json

New login workflow

Starting the Custom Application locally now redirects you to the login page of the Merchant Center production environment (as defined in the Custom Application config). Upon successful login, you are redirected back to your local development server with a valid session.

Recommended setup for EntryPoint

Changes to the CLI

• In mc-scripts, the build command additionally compiles the index.html by default.
  • Running the compile-html command by default should not be necessary anymore. However, you can pass --build-only to the build command to opt-out of the compilation step, in case you want to run it separately, for example to use the --transformer.
• Running the compile-html command by default does not print to stdout the JSON string with the security headers. You can opt into the old behavior by passing the --print-security-headers option.
• The --inline-csp of compile-html has been dropped, as it's now the built-in behavior.
• The dist folder created by the build command has been removed. Instead, the build command writes the production bundles directly into the public folder.

Better deployments support

With the new improvements in the developer tools, it's now even simpler to deploy a Custom Application to all the major hosting services. In fact, you can now take advantage of the GitHub integration with some of those hosting providers, without any extra effort around configuration.

Now most of the things are built-in and defined as defaults, removing the need to dynamically create a configuration file. As a result, configurations for the hosting provider can be defined statically, thus allowing to fully use the GitHub integration features.

Changes to Test Utils

• The disableApolloMocks option has been removed. By default, the Apollo mocks are deactivated. This is to encourage mocking via Mock Service Worker. To opt into the usage of Apollo mocks, you only need to pass the mocks property with a non-empty array. See Testing for more information.
• The disableAutomaticEntryPointRoutes option now defaults to false. This means that when rendering the <ApplicationShell>, you should not use the render function but pass the application component using children.
  const EntryPoint = () => ( <ApplicationShell environment={window.app} applicationMessages={loadMessages} > <AsyncApplicationRoutes /> </ApplicationShell> );
• The application View permission is automatically applied to the project object, based on the environment.entryPointUriPath value. You can always override the permission values by explicitly assigning project.allAppliedPermissions.
• The deprecated project.allAppliedMenuVisibilities option has been removed.
• The deprecated permissions option has been removed. Use project.allAppliedPermissions instead.
  // Before { permissions: { canManageProducts: true; } } // After { project: { allAppliedPermissions: [{ name: 'canManageProducts', value: true }]; } }
  You can also use the helper function mapResourceAccessToAppliedPermissions (recommended)
  import { mapResourceAccessToAppliedPermissions } from '@commercetools-frontend/application-shell/test-utils'; { project: { allAppliedPermissions: mapResourceAccessToAppliedPermissions([ PERMISSIONS.View ]) }, }
  or the denormalizePermissions function.
  import { denormalizePermissions } from '@commercetools-frontend/application-shell/test-utils'; { project: { allAppliedPermissions: denormalizePermissions({ canManageProducts: true, }); } }

The Custom Application Starter template has been rewritten from scratch, to provide a better experience to new developers working on Custom Applications.

Below an overview of the most important changes:

{/* <!-- more */}

• The template now has more built-in dev tools, like ESLint and Prettier.
• The template README has been cleaned up a bit.
• The template uses the new React JSX transform.
• The template uses the new menu links in application config.
• The template has a nicer landing/welcome page with useful links to get started.
• The template has a channels page, that fetches channels and renders them in a table. This is a good showcase of some of our best practices, for example to use hooks, to use GraphQL, to use notifications, to render data in a table (with pagination), etc.
• The template has React-Testing-Library tests, including mocking GraphQL and using test data.

This release contains breaking changes.

This version does not contain explicit changes in our packages but mainly updates to major versions of some of the depended upon libraries. For instance:

• @commercetools-frontend/ui-kit and all @commercetools-uikit/* packages have been updated to v12.
• react and react-dom have been updated to v17.
• graphql has been updated to v15.
• webpack has been updated to v5

{/* <!-- more */}

Migrating UI Kit packages

Constraints

Text

{/* vale off */}

{/* vale on */}

{/* vale off */}

{/* vale on */}

Link

Tag

SecondaryButton

This release contains breaking changes.

Most of the rules have stayed the same, however you may need to adjust or fix some depending on your usage.

Follow the steps below to migrate your ESLint config to the new version.

{/* <!-- more */}

Migrating @commercetools-frontend/eslint-config-mc-app

Simply remove all ESLint related dependencies that where previously required as peer dependencies.

As a reminder, the ESLint config can be used as following:

We are really excited about it and we hope you find it useful too.

This release contains breaking changes.

Follow the steps below to migrate your Custom Application to the new versions.

{/* <!-- more */}

Migrating to Apollo Client v3

Migrating Apollo imports

About the new Apollo Cache

If that is the case, you need to configure the Apollo cache according to your needs, as only you know what the best caching strategy for your Custom Application is.

Changes about Apollo query variables and context

• target
• projectKey

Enforcing a valid context object

• useMcQuery
• useMcLazyQuery
• useMcMutation

Changes about the mc-scripts CLI

Removing deprecated options from compile-html

For example, to run locally the Custom Application using the production bundles:

Removing the mc-http-server package

New command serve

Before:

After:

Removing the extract-intl command

Before:

After:

Changes about the experimentalRenderAppWithRedux from test utils

Removing the deprecated options from application-shell

Furthermore, the new configuration process tries to infer as much information as possible to reduce the amount of required fields.

{/* <!-- more */}

Migrating to the new configuration file format

The new configuration file is a JSON file with one of the following names:

• .custom-application-configrc
• .custom-application-config.json
• custom-application-config.json

That's it! All other values are inferred from the config, like the Content-Security-Policy (CSP) headers, etc.

Migrating mc-scripts commands

JSON Schema support for VSCode

In the VSCode settings (either user settings or workspace settings), reference the schema JSON as described below:

With that, the editor can offer autocompletion and validation of the JSON properties.

If you are using the [new application config file][/development/application-config], you can ignore the migration steps as the hostnames are automatically configured.

Here are the steps to take.

{/* <!-- more */}

1. Update dependencies

To update all the application kit packages to a specific version, you can use the following script:

2. Update the env.json

For example:

3. Update the headers.json

Update the Content Security Policy to allow both new and legacy hostnames.

For example:

4. Re-deploy the Custom Application

That's it. Re-deploy the Custom Application with the updated configuration. Users can now access the Custom Application using both new and legacy hostnames (for backwards compatibility).