Converting an extension into an app
What is an app in the context of Contentful? Apps are the next generation of UI extensions. Inheriting most of the functionality that UI Extensions support and improve upon it, apps help everyone -- developers and non-developers alike -- install and configure Contentful extensions more easily than before. With apps, you can further customize Contentful to suit your own needs and workflows.
Using the App Framework, you can create private apps for your own space or organization. Not sure where to begin? Check out the public apps available (for free!) from the Contentful marketplace.
Advantages of apps over UI extensions
The main benefit of apps is that they are out-of-the-box solutions. Apps are meant to create user-friendly installation flows, transforming a space without complex interactions. In contrast, UI extensions need to be configured by the developers of each extension.
Apps are defined inside a single Contentful organization as a template. This template, called an
AppDefinition, is then referenced by the installation of the app inside a space environment. Each installation saves a set of installation parameters. This allows for easy maintenance of apps when installed across multiple spaces or organizations. Apps can be private to organizations or published publicly on the Contentful marketplace.
Not sure if transforming an existing UI extension into an app is worth it? Try thinking about these criteria:
- The extension integrates your SaaS product with Contentful and you want to publish it on the marketplace
- The extension is shared across multiple spaces or multiple organizations
- Non-technical users should be able to easily install and configure the app
- The extension requires additional complex configuration of the space on installation
- The extension requires occasional updates and these should be propagated to all instances of the extension
Migrating a UI extension to an app
For the most part, UI extensions and apps are compatible. However, a few differences in apps and UI extensions do exist, which result in the need for code changes during the migration process.
The following gives you an overview on the steps necessary to transform your extension into an app.
Think of an
AppDefinition as something similar to a template for a UI extension. This template is then referenced by an
AppInstallation inside a space environment, expressing the installation of the app in said space environment. The installation maintains a link to the definition and this link is resolved when the app is loaded by the user. This means that you only have to maintain exactly one copy of your central configuration for the app and it is no longer copied into every environment as was the case with UI Extension installations.
App definitions have three main configuration options:
name: Name of the app, same as for extensions
src: URL of the app frontend
locations: Array of locations the app can be shown in
parameters: Definitions of app instance paramters
You can create a new app definition in your organization settings or via the Management API. Please note that to create or update an
AppDefinition, the organization owner, admin or developer role is required.
Apps only support hosting via external urls which are defined by the
src attribute of the
AppDefinition. You need to host the static assets of your app with a provider of your choice. Please remember that
https support is required for all other domains than
If you've used
create-contentful-extension to set up your extension project, you can build the static extension assets with
npm run build. Everything located in
./build then needs to be hosted. For local testing, you can modify the
start command in
package.json to include the
--serve-only flag. It will then no longer try to install the UI extension in your space but still serve your app on
Implementing the config location
Once you've hosted your app and added the
AppDefinition for your app, it will appear as a private app under
Apps in any of your organization's spaces. When you select it from your list, the web app will navigate you to the
app-config location for the app and try to load it from the
The app configuration screen is the most complex element of an app. How to implement it in detail is outlined in the app tutorial. Note that you don't have to implement it initially: a basic version allowing installation of your app will be rendered by default.
Publishing an app on the marketplace
If you are interested in releasing your app on the Contentful marketplace, please let us know by filling out this form.