Overview

5 min

The Optimizely Connect Platform (OCP) app development lifecycle guides you from initial planning to public release. Each of the following stages depends on the previous one:

Plan your app – Choose your app type, plan your version strategy, and verify prerequisites.

Build your app – Configure the app manifest, define the settings form, add dependencies, and implement app logic.

Test your app – Write unit tests, test locally with ocp dev, and deploy to preview tracks that your test accounts follow.

Release your app – Validate, submit for review, and release your app to the OCP App Directory, the marketplace where users discover and install OCP apps.

Troubleshoot your app – Use app logs and Activity Log notifications to debug issues.

Prerequisites

Before you start, ensure you have the following:

OCP CLI – Install the OCP command-line interface and configure it with your Developer Portal API key. See Developer Portal overview.

Node.js – Install Node.js 22 or later. OCP apps require Node.js 22 or later. See Node22 migration guide for details.

Access to an OCP instance – Have access to an OCP instance where you can install and test your app. You do not need a Developer role. If you do not have access, ask an administrator of the organization to grant you any role on that instance through the Admin Center. See Developer accounts and organizations for information.

Deploy, install, and release

The following CLI actions move your app from your machine to an end-user's OCP account:

Deploy – Run ocp app deploy to build your local code in OCP and publish it to your own preview track, dev/USERNAME. OCP derives the version from your app content, so you do not set a version in app.yml. Preview versions never enter review. To deploy to a shared track, such as one for testers, run ocp app deploy --preview-track beta/NAME.

Install – Run ocp directory install YOUR_APP_ID TRACKER_ID once to add the app to a test account. The tracker ID is the unique identifier for an OCP account. Without a version, the installation follows your dev/USERNAME track. Every later deploy to the track moves the installation to the version you deployed. To follow a shared track, append --preview-track beta/NAME. Install triggers the app's onInstall lifecycle hook (the function that runs when the app is added to an account).

Release – Run ocp app promote --from dev/USERNAME --to 1.0.0 to release the version your track runs as a semantic version (semver). To release your working directory instead, run ocp app deploy --version 1.0.0. The command builds the release version, starts the Optimizely code review process, and publishes the version after approval. End-users install public apps from the OCP App Directory.

ocp app deploy requires runtime: node22 or later in app.yml. See Deploy apps with preview tracks for details.

Prepare, publish, and install

Legacy

ocp app prepare is deprecated. It still works and prints a deprecation warning. Use it only for apps that set a version in app.yml and have not moved to ocp app deploy, such as apps on a runtime earlier than node22. ocp directory publish is not deprecated.

The following CLI actions move an app that uses the legacy flow from your machine to an end-user's OCP account. Each step depends on the previous one:

Prepare – Run ocp app prepare to upload your local code and build the app in OCP. Only a prepared app can be published. For release versions, such as versions without a -dev pre-release tag, ocp app prepare also starts the Optimizely code review process. See App versioning for details. You cannot publish until your review is approved.

Publish – Run ocp directory publish YOUR_APP_ID@VERSION to make a prepared version available in the OCP App Directory. After you publish, the version is available to install, but is not yet active in any account.

Install – Add a published version to a specific OCP account, identified by its tracker ID (the unique identifier for an OCP account). End-users install public apps from the App Directory. Developers install pre-release, private, or test versions from the CLI with ocp directory install YOUR_APP_ID@VERSION TRACKER_ID. Install triggers the app's onInstall lifecycle hook (the function that runs when the app is added to an account).

Run ocp directory install only once per app and OCP account. After the initial install, OCP automatically upgrades the installation when you publish a higher patch or minor version. Major version upgrades require a manual reinstall. See App versioning for details.

Follow a typical development path

The following steps reflect the most common sequence for developing and releasing an OCP app:

Develop locally with ocp dev.

Run ocp app deploy to build and publish the app to your dev/USERNAME preview track.

Run ocp directory install YOUR_APP_ID TRACKER_ID once to add the app to a test account that follows your track.

Iterate. Each ocp app deploy moves the test installation to the version you deployed.

Run ocp app promote --from dev/USERNAME --to 1.0.0 to release the version. It enters review and is published after approval.

End-users install from the App Directory.

Iterate with preview tracks

Deploy your app to a preview track, such as dev/jdoe, instead of bumping a -dev version for each change. Run the following command:

ocp app deploy

ocp app deploy builds and publishes your app in one step. OCP derives the version from your app content and moves every installation that follows the track to that version. OCP never reviews preview versions. The App Directory lists them only for accounts that install or follow them. Apps that cannot use ocp app deploy yet follow the legacy prepare, publish, and install steps.

See Deploy apps with preview tracks for details.

For data sync implementation guides, see Data syncs.

For Mark (Optimizely Agent Platform) tools implementation guides, see Add a custom tool to Mark and the Mark tool reference app end-to-end guide.