https://github.com/commercetools/connect-application-kit
Tools and components for developing Connect Applications ðŸ›
https://github.com/commercetools/connect-application-kit
Last synced: 12 months ago
JSON representation
Tools and components for developing Connect Applications ðŸ›
- Host: GitHub
- URL: https://github.com/commercetools/connect-application-kit
- Owner: commercetools
- License: mit
- Created: 2022-07-29T10:36:37.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-05-06T07:55:42.000Z (about 1 year ago)
- Last Synced: 2025-07-18T05:09:17.505Z (12 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.73 MB
- Stars: 11
- Watchers: 5
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
commercetools Connect Application Kit [BETA]
✨ Monorepository with tools and components for developing connect applications ðŸ›
> Connect starter kit and tools are marked as beta and subject to change. Use with caution.
## Template Features
- **Typescript & Javascript**: languages supported
- **Express**: Web server framework
- **commercetools sdk**: Embedded sdk library for commercetools specific implementation
- **Buildpack support**: Tooling to build production-ready container images from source code without a Dockerfile
- **Local development utilities**: Basic yarn tools to build, start , test, lint & prettify code
- **Structured logging library**: JSON formatted logger with log levels
- **Tests**: Basic tests setup for application
## Getting started
If you are developing a connect application, you can start by installing one of our [templates](./application-templates) using the `create-connect-app` CLI.
```bash
$ npm install --global @commercetools-connect/create-connect-app
$ create-connect-app first-connect-application --template [typescript | javascript]
# or
$ npx @commercetools-connect/create-connect-app@latest first-connect-application --template [typescript | javascript]
```
# Developing connect applications
Before starting the development, we advise the developers to create a `.env` file in order to help them in local development.
For that, we also have a template file `.env.example` with the required environement variables for the project to run successfuly. To make it work, rename the file from `.env.example` to `.env`. Remember to fill the variables with your values.
### Install the dependencies (uses yarn workspaces):
```bash
$ yarn
```
### To run the tests:
```bash
$ yarn test
# or
$ yarn test:watch
```
### Build the application
```bash
$ yarn build
# or
$ yarn build:watch
```
### Run the application locally
```bash
$ yarn start
# or
$ yarn start:dev
```
# Connect Certification
In order to deploy your connect application on commercetools provided infrastructure, it needs to reviewed by certification team. This can be requested by creating a listing using connect APIs (not yet released)
A default starter pack has a directory structure as shown below, repository should be a mono repo setup where you can choose to have more than one application in a single connector if needed
```
├──
│ └── readme.md
├──
│ ├── src
│ ├── tests
│ └── package.json
├──
│ ├── src
│ ├── tests
│ └── package.json
└── connect.yaml
```
You can choose to remove/add applications based on needs with similar repository structure.
Connect deployment details needs to be specified in `connect.yaml` which is required information needed for certificaiton of the application
Buildpack is used to build artifacts to deploy , use `npm start` or `Procfile` to define the default entry point
# Deployment config
Connect supports 3 types of application which needs to set as `applicationType` in the config file
1. `service` - Standalone application which can do a specific task triggered by any HTTP method (can be used for API extensions or as a webhook to other systems). HTTP url will be generated and exposed as result of the deployment.
2. `event` - Event topics & related consumer services to be able to receive events and perform any task asynchronously (can be used for Subscriptions). A topic will be generated and exposed as result of the deployment
3. `job` - Task which needs to be performed at regular basis with defined intervals, these tasks can be scheduled using cron expression
A sample deployment config looks like this, refer below for more detailed information on each property
```yaml
deployAs:
- name: app1
applicationType: service
endpoint: /app1
scripts:
postDeploy: npm install && npm run build && npm run connector:post-deploy
preUndeploy: npm install && npm run build && npm run connector:pre-undeploy
configuration:
standardConfiguration:
- key: ENVIRONMENT_VARIABLE_1
description: description variable 1
securedConfiguration:
- key: ENVIRONMENT_VARIABLE_2
description: description variable 2
- key: ENVIRONMENT_VARIABLE_3
description: description variable 3
- name: app2
applicationType: job
endpoint: /app2
properties:
schedule: "0 0 * * *"
configuration:
standardConfiguration:
- key: ENVIRONMENT_VARIABLE_1
description: description variable 1
- key: ENVIRONMENT_VARIABLE_2
description: description variable 2
- name: app3
applicationType: event
endpoint: /app3
configuration:
securedConfiguration:
- key: ENVIRONMENT_VARIABLE_1
description: description variable 1
- key: ENVIRONMENT_VARIABLE_2
description: description variable 2
- key: ENVIRONMENT_VARIABLE_3
description: description variable 3
- name: app4
applicationType: merchant-center-custom-application
endpoint: /app4
configuration:
standardConfiguration:
- key: ENVIRONMENT_VARIABLE_1
description: description variable 1
securedConfiguration:
- key: ENVIRONMENT_VARIABLE_2
description: description variable 2
- key: ENVIRONMENT_VARIABLE_3
description: description variable 3
```
- Multiple applications of same type can be setup
- A schedule property is additional mandatory information needed to be able to schedule the job
- Event type of application needs to be defined together with a service type of application with mandatory subscriber information to process the received event
## Property definition
- `name` - Folder name of respective application component from the root of monorepo which will be used as identifier of the application. Deployment output url, topic & schedule can be fetched based on this reference
- `applicationType` - Type of deployment . Can be one of `service`, `event`, `job` and `merchant-center-custom-application`
- `endpoint` - Point of entry for respective application component
- `scripts.postDeploy` - Post-deploy script to execute after the connector deployment process
- `scripts.preUndeploy` - Pre-undeploy script to execute before the connector undeployment process
- `configuration` - Definiton of all environment variables needed by the application, customer will be responsible to provide value for these variables when choosen to deploy. You need to choose between `standardConfiguration` and `securedConfiguration`. `standardConfiguration` for customer provided values to be saved as plain text , `securedConfiguration` for customer provided values to be secured and stored in encrypted format. configurations can be marked `required` depending on application implementation and also provided a `default` value if needed
- `schedule` - Schedule expression for job applications, it need to be input of type cron expression