Plan your app
Plan your app's scope, type, and versioning strategy before you start building.
Prerequisites
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](../Get started/developer-portal-overview.mdx).
- Node.js – Install Node.js 22 or later. OCP apps require Node.js 22 or later. Install Node.js 22 or later. OCP apps require Node.js 22 or later. See [supported Node.js versions] 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 Portal overview](../Get started/developer-portal-overview.mdx) for information.
Key concepts
The following terms are used throughout this guide:
- App – A custom-built application deployed to OCP, consisting of a manifest (app.yml), source code, schema definitions, and form definitions.
- App version – A specific release of an app, identified by APP_ID@VERSION, such as [email protected]. Versions follow semantic versioning, a three-part numbering system (major, minor, patch) that indicates the scope of a change, with optional pre-release tags.
- Installation – An instance of an app running in a specific OCP account. Each installation has its own settings, storage, and lifecycle state.
App structure
An OCP app consists of a manifest (app.yml), source code, schema definitions, and form definitions. The app manifest defines the functionalities provided by your app. See App structurefor a breakdown of the project layout.
Runtime environment
OCP apps run on a managed, serverless Node.js platform. Apps are written in TypeScript and run on Node.js 22. See Configure your development environment for setup instructions.
Choose your app type
OCP supports several app types. Choose the type that fits your use case.
Data sync source
A data sync source provides data from an external system to OCP through the Sync Manager. Use this type to import data from an external system into OCP. Users can then access this data in Optimizely products, such as Optimizely CMS.
See Data sync source for implementation details.
Data sync destination
Receives data from OCP and sends it to an external system through the Sync Manager. Use this type to export Optimizely data to an external platform, for example, Content Management System (CMS) content from Graph or assets from Optimizely Content Marketing Platform (CMP).
See Data sync destination for implementation details.
Opal tool
Extends the Opal AI assistant with custom tool capabilities. Use this type when you want the Opal assistant to retrieve data or perform actions in external systems on behalf of the user.
See the Opal tool reference app end-to-end guide for a complete walkthrough.
CMS UI extension
Beta
The following feature is in beta.
Contributes UI into Optimizely CMS. OCP supports three surfaces, the content editor side panel, sidebar, a full page, view, and a custom editor for a single content property, property-editor. Additional panel types are planned. The UI is backed by an OCP function that holds credentials and proxies requests to external services. Use this type to extend the CMS editor experience, for example, a content-aware assistant in the side panel, a browsable media library as a full page, or a color picker for a string property.
See CMS UI extensions for implementation details.
Generic
Supports functions, jobs, a settings form, and lifecycle hooks. Use this type for integrations that do not fit one of the specialized types above. Generic apps can use OCP capabilities, such as storage, and communicate with Optimizely and external services through APIs.
Plan your version strategy
OCP uses semantic versioning (MAJOR.MINOR.PATCH) with pre-release tags:
Development
Use -dev tags, such as 1.0.0-dev.1, during development and testing. Dev versions are limited to your associated OCP accounts, cannot be shared with other accounts, and bypass the app review process. Increment the dev tag as you iterate, like 1.0.0-dev.2, 1.0.0-dev.3.
Pre-release testing
Beta
The following feature is in beta.
Use -beta tags, like 1.0.0-beta to share pre-release versions with selected testers. Beta versions can only be installed with the OCP CLI. Beta versions require review approval.
Preview tracks
Experimental
The following feature is experimental.
Iterate on a preview track, such as dev/jdoe or beta/feature-x. OCP derives the version from your app content. OCP never reviews preview versions, and the App Directory lists them only for accounts that install or follow them. Apps that run on runtime: node22 or later and depend on @zaiusinc/app-sdk 3 or later can use them. See Deploy apps with preview tracks.
Production release types
When your app is ready for production, choose one of the following release types:
- Normal version – Remove the pre-release tag, like 1.0.0. The app is publicly available to all Optimizely customers in the App Directory.
- Private version – Use the -private tag, like 1.0.0-private. The app is released to production, but availability is limited to selected OCP accounts. Use this when you want to release production-ready functionality but control who can install the app.
Both release types require review approval by Optimizely.
Auto-upgrade behavior
OCP handles version upgrades differently depending on whether the update is a major or non-major release.
OCP auto-upgrades existing installations when you publish a non-major version update, like MINOR or PATCH. For example, publishing version 1.1.0 automatically upgrades all installations running 1.0.x. Major version updates such as 1.0.0 to 2.0.0 require the end-user to click Upgrade in the App Directory.
Pre-release versions also auto-upgrade within the same tag. For example, publishing 1.0.0-dev.2 automatically upgrades installations running 1.0.0-dev.1.
See App versioning for details on how OCP handles version upgrades.