This repository contains the source code for partner apps on the marketplace and helpful resources to build your own apps for Contentful.
Head over to the marketplace and follow the installation flow to set up any of the apps in your Contentful space.
The Marketplace Partner Apps repo is maintained as a single repository for apps, containing several ecosystem partner apps + the tools needed to build and maintain them. The apps
folder contains each partner app, and each sub-folder within apps
should contain all the code necessary to build, test, and deploy your app without references to other apps or folders.
The marketplace-partner-apps
repo uses Circle CI (configured in .circleci/config.yml
) to deploy itself, and Lerna (configured in lerna.json
) to manage the collection of partner apps.
When a PR is opened that introduces a new app, a GitHub action runs to do some extra validation to ensure that the PR is ready for Contentful review. Specifically, here are some criteria it checks for:
Have a package.json
file with the following scripts
:
start
"vite"
install-ci
npm ci
that installs off of a package-lock file.build
"vite build"
is common for most apps without specific needs, though whatever tool or process you prefer is fine so long as it creates artifacts that can be referenced in the deploy step.test
"vitest"
is common for many apps and should be considered if you do not have complicated tests.lint
Ensure that the package version number in your package.json
file is below 1.0.0. The version of 1.0.0 is reserved for initial release.
Have a LICENSE
file at the root of your app directory with a valid open source license agreement.
Use TypeScript. We require this to ensure code quality and maintainability for the marketplace apps.
Ensure dependencies are up to date. The validation checks will provide warnings if a new app has outdated dependencies.
[!NOTE] > Please note that dependabot is enabled in this repo and will run automatically. While it will attempt to only upgrade dependencies without breaking changes, it is possible it will still introduce issues. Creating and maintaining comprehensive tests is critical to preventing code and build issues. See Keeping dependencies up to date for more details.
After a new app has been introduced into the repo, the Contentful team will make a couple of updates:
All code deployed by the marketplace-partner-apps
repo must be hosted by Contentful. The Contentful team will add the necessary deploy
script that will deploy your app to an app definition in our shared, official space. Please do not update it in subsequent changes/pull requests; doing so will prevent future updates from being deployed to your marketplace app definition.
Add the new app to the repo's dependabot configuration.
Add the new app to the release-please-config.json
file so that the release workflow will include the new app. The release workflow encapsulates versioning as well as the creation and maintenance of a changelog.
When you are ready to submit your app to the marketplace apps repo, clone the repo locally, create a new branch with a name that follows Conventional Commits standards (see below) for the app/changes you are introducing, and create a pull-request against the main
branch. A Contentful team member will review your PR soon and let you know if any changes or clarifications are needed. To ensure the fastest approval time on your PR, make sure you:
feat
.marketplace-partner-apps
is intended to be open and transparent and any external resources will be highly scrutinized.It is the responsibility of all partner app developers to ensure their app is kept up to date with the latest versions of all dependencies required by their app. This is required not only to ensure their app continues to function as expected alongside the constantly evolving Contentful platform, but also to ensure that critical security updates are applied in a timely fashion and are not slowed down by out of date cross dependencies.
To keep dependencies up to date, Contentful uses Dependabot in this repository. Dependabot will:
[!TIP] We recommend specifying bare versions (e.g.
1.2.3
) of dependencies in your package.json file vs. a range of versions (e.g.1.2.x
or~1.2.3
). Dependabot will increment versions in your package.json file automatically.
As an app developer, it is important to review and approve any dependency update PRs assigned to you on a frequent basis. Specifically we ask that you:
The best way to get started on app development is with our create-contentful-app CLI tool. This tool will bootstrap a brand new project with all the boilerplate code you need to start building an app. If you are interested in learning how to build a simple example app, you can check out our tutorial.
Detailed documentation can be found in the App SDK documentation and the Management HTTP API reference documentation.
Please note that each app has its individual source code license associated with it. Refer to the LICENSE file in the apps root folder.
If you require support, or want to request a new feature then please use the appropriate support channel which will be listed with the app on our app marketplace.