Learn how to deploy your customization to Connect.
Prerequisites
Before you get started, you need to have:
- A commercetools Composable Commerce Project (get started) and one of the following:
- A Custom Application configured in the Merchant Center. When configuring your Custom Application, enter a dummy URL value for Application URL as you will update it after the Custom Application is deployed.
- A Custom View configured in the Merchant Center. When configuring your Custom View, enter a dummy URL value for Application URL as you will update it after the Custom View is deployed.
Create your Application
Custom Application
-
Install a Connect starter template.
-
Open the
merchant-center-custom-application
folder in the Connect starter template and install the Custom Applications starter template inside this folder. -
Add your environment variables to
custom-application-config.mjs
.const config = { name: 'Example Custom Application', entryPointUriPath: '${env:ENTRY_POINT_URI_PATH}', cloudIdentifier: '${env:CLOUD_IDENTIFIER}', env: { development: { initialProjectKey: 'my-project-key', }, production: { applicationId: '${env:CUSTOM_APPLICATION_ID}', url: '${env:APPLICATION_URL}', }, }, oAuthScopes: { view: ['view_products'], manage: ['manage_products'], }, icon: '${path:@commercetools-frontend/assets/application-icons/rocket.svg}', mainMenuLink: { defaultLabel: 'Template starter', labelAllLocales: [], permissions: [PERMISSIONS.View], }, submenuLinks: [ { uriPath: 'channels', defaultLabel: 'Channels', labelAllLocales: [], permissions: [PERMISSIONS.View], }, ], }; export default config;
-
Update the value of
entryPointUriPath
inconstants.ts
/constants.js
.export const entryPointUriPath = typeof window === 'undefined' ? process.env.ENTRY_POINT_URI_PATH : window.app.entryPointUriPath;
-
Open
connect.yaml
in the root of the Connect starter template and replace it with the following:- Enter a
name
for the application. - Define the environment variables you included in
custom-application-config.mjs
.
deployAs: - name: name-of-custom-application applicationType: merchant-center-custom-application configuration: standardConfiguration: - key: CUSTOM_APPLICATION_ID description: the Custom Application ID required: true - key: CLOUD_IDENTIFIER description: The cloud identifier default: 'gcp-eu' - key: ENTRY_POINT_URI_PATH description: The Application entry point URI path required: true
APPLICATION_URL
is automatically provided by Connect and you do not need to define it inconnect.yaml
.CUSTOM_APPLICATION_ID
andENTRY_POINT_URI_PATH
must only be used for the Custom Application’sApplication ID
andApplication entry point URI path
respectively. - Enter a
-
Push your code to a GitHub repository and make a new release. Your release must have a Git tag.
Your GitHub repository can be public or private. If you are using a private repository, you must provide access to the GitHub machine user connect-mu.
Custom View
-
Install a Connect starter template.
-
Open the
merchant-center-custom-view
folder in the Connect starter template and install the Custom View starter template inside this folder. -
Add your environment variables to
custom-view-config.mjs
.const config = { name: 'Example Custom View', cloudIdentifier: '${env:CLOUD_IDENTIFIER}', env: { development: { initialProjectKey: 'my-project-key', }, production: { customViewId: '${env:CUSTOM_VIEW_ID}', url: '${env:APPLICATION_URL}', }, }, oAuthScopes: { view: ['view_products'], manage: ['manage_products'], }, }; export default config;
-
Open
connect.yaml
in the root of the Connect starter template and replace it with the following.- Enter a
name
for the application. - Define the environment variables you included in
custom-view-config.mjs
.
deployAs: - name: name-of-custom-view applicationType: merchant-center-custom-view configuration: standardConfiguration: - key: CUSTOM_VIEW_ID description: the Custom View ID required: true - key: CLOUD_IDENTIFIER description: The cloud identifier default: 'gcp-eu'
APPLICATION_URL
is automatically provided by commercetools Connect and you do not need to define it inconnect.yaml
.CUSTOM_VIEW_ID
must be used only for the Custom View’sView ID
. - Enter a
-
Push your code to a GitHub repository and make a new release. Your release must have a Git tag.
Your GitHub repository can be public or private. If you are using a private repository, you must provide access to the GitHub machine user connect-mu.
Publish and deploy your application
You can publish and deploy your application using either the Connect API or the Merchant Center. You will require the Application ID
and Application entry point URI path
of your configured Custom Application or configured Custom View.
Use the Connect API
- Create a Connector which references the GitHub repository and release tag of your application.
- Publish your Connector using the preview or publish flow.
- Deploy the Connector with the correct configuration values:
- For Custom Applications, the
CUSTOM_APPLICATION_ID
must be theApplication ID
andENTRY_POINT_URI_PATH
must be theApplication entry point URI path
of your configured Custom Application. - For Custom Views, the
CUSTOM_VIEW_ID
must be theView ID
of your configured Custom View.
- For Custom Applications, the
- Once your Connector is deployed, get the Deployment and copy the value of
applications[*].url
. This is the URL where your Custom Application or Custom View is deployed. - In the Merchant Center, update the Application URL of your Custom Application or Custom View with the URL where it is deployed.
Use the Merchant Center
- Create an Organization Connector which references the GitHub repository and release tag of your application.
- Publish your Connector using Request Preview or Publish for private use.
- Install the Organization Connector with the correct configuration values:
- For Custom Applications, the
CUSTOM_APPLICATION_ID
must be theApplication ID
andENTRY_POINT_URI_PATH
must be theApplication entry point URI path
of your configured Custom Application. - For Custom Views, the
CUSTOM_VIEW_ID
must be theView ID
of your configured Custom View.
- For Custom Applications, the
- Open Manage connectors and click Installations. When the Status of the Connector is
Installed
, click the Connector and select your application from the list. Copy the value of theURL
field. This is the URL where your Custom Application or Custom View is deployed. - Update the Application URL of your Custom Application or Custom View with the URL where your Custom Application or Custom View is deployed.
Test your deployment
Install the Custom Application in the Merchant Center and access it in your Projects. Install the Custom View in the Merchant Center and access it in your Projects.