This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Developing a Connect application

Learn how to create and structure Connect applications.

What are Connect applications?

Connect applications are the applications that are hosted and run by Connect once their associated Connector has been published. Connect applications can be developed using JavaScript/TypeScript or Java.

Follow this guide to learn how to structure your Connect application for use in a Connector. Links to starter templates are also provided.

Requirements

Developing Connect applications requires a commercetools Composable Commerce Project and a GitHub account. The following requirements are based on whether you are developing Connect applications using JavaScript/TypeScript or Java.

JavaScript/TypeScript

Node v16.x LTS (or later)
npm or Yarn

Java

Java v11 LTS (or later - v17 LTS is preferred)
Maven
Knowledge of the Spring Boot framework

It is currently recommended to create Connect applications using JavaScript or TypeScript. For more information on creating Connect applications with Java, please contact support.

Install a starter template

The easiest way to start developing Connect applications is to use one of the starter templates.

We recommend creating a new Connect application using create-connect-app, which automatically sets up one of the starter templates for you.

To do so, you must first install the Create Connect App.

npm install --global @commercetools-connect/create-connect-app

Then you can install a template for JavaScript or TypeScript.

create-connect-app first-connect-application --template javascript

create-connect-app first-connect-application --template typescript

Use the correct directory structure

You should structure your Connect application as in the following example. This directory structure is reflected in the starter templates.

├── < docs >
│ └── readme.md
├── < event >
│ ├── src
│ ├── tests
│ └── package.json
├── < job >
│ ├── src
│ ├── tests
│ └── package.json
├── < service >
│ ├── src
│ ├── tests
│ └── package.json
├── < merchant-center-custom-application >
│ ├── src
│ ├── tests
│ └── package.json
└── connect.yaml

The folders event, job, service, and merchant-center-custom-application represent the possible Connect application types that can be run in your Connector. You can remove folders of applications you do not want to develop, or you can rename them to reflect the Connect application's purpose. A Connector can have one or more Connect applications of the same type.

You must specify the deployment information of your Connect applications in connect.yaml. This file contains information that is required to create, publish, and deploy Connect applications.

Configure connect.yaml

connect.yaml is located in the root of the Connect application and contains the necessary configuration and scripts for it to operate. The following example connect.yaml file is found in the starter template.

Example connect.yamlyaml

deployAs:
  - name: service
    applicationType: service
    endpoint: /service
    scripts:
      postDeploy: npm install && npm run connector:post-deploy
      preUndeploy: npm install && npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Composable Commerce Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Composable Commerce Project is hosted
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools Composable Commerce Project
  - name: job
    applicationType: job
    endpoint: /job
    properties:
      schedule: '*/5 * * * *'
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Composable Commerce Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Composable Commerce Project is hosted
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools Composable Commerce Project
  - name: event
    applicationType: event
    endpoint: /event
    scripts:
      postDeploy: npm install && npm run connector:post-deploy
      preUndeploy: npm install && npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Composable Commerce Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Composable Commerce Project is hosted
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools Composable Commerce Project
  - name: merchant-center-custom-application
    applicationType: merchant-center-custom-application
    endpoint: /
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Composable Commerce Project
          required: true
          default: 'default-key'
        - key: CTP_REGION
          description: Region where the commercetools Composable Commerce Project is hosted
          required: true
        - key: APPLICATION_ID
          description: The Custom Application ID
          required: true
      securedConfiguration:
        - key: CTP_CLIENT_ID
          description: client_id of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_CLIENT_SECRET
          description: secret of an API Client for the commercetools Composable Commerce Project
          required: true
        - key: CTP_SCOPE
          description: scope of an API Client for the commercetools Composable Commerce Project

The values of connect.yaml are as follows.

Key	Description
`name`	Identifier of the application deployment. The Deployment's output URL, topic, and schedule are fetched based on this reference. `name` must match the folder for the application in your repository.
`applicationType`	Can be `event`, `job`, `service`, or `merchant-center-custom-application`.
`endpoint`	The `endpoint` naming used by the Deployment URL. The URL is constructed using the format `{connect-provided-url}/{endpoint}` (for example: `https://service-11111111-1111-1111-1111-111111111111.europe-west1.gcp.commercetools.app/service`)
`configuration`	Defines the standard and secret environment variables needed by the Connect application. The client defines values for these environment variables when deploying the Connector. If `required` is `true`, a value for the environment variable must be included. Default values can only be specified for standard environment variables and will be used as fallback values if not provided during deployment.
`properties`	Placeholder for all additional arguments in hosting a Connector. Currently supports a schedule for `job` applications.
`properties.schedule`	Cron expression for `job` applications.

event applications must be defined with a service application with mandatory subscriber information to process the received event.

Manage the application with Yarn commands

Use the following Yarn commands to manage your Connect application.

Install dependencies

Dependencies are installed using Yarn Workspaces.

yarn

Run tests

yarn test

# or
yarn test:watch

Build the application

yarn build

# or
yarn build:watch

Run the application locally

yarn start

# or
yarn start:dev

Testing your Connect application

It is recommended to implement unit and integration test cases as part of application development and follow a test-driven development approach.

These test cases are reviewed and also executed during the publishing process. Scripts to run tests should be defined in a test script.

Connect application templates provide sample implementation of testing using Jest.

Upload and create a release on GitHub

After finishing the development of a Connect application, you should push it to a GitHub repository. The Connect application should be released on GitHub with a Git tag so that specific application releases can be referenced by the Connector.

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 before publishing your Connector.

Next steps

Once your Connect application, GitHub repository, and Git tag are ready, you can follow our getting started guide to create a Connector using your Connect application.