Introducing apps

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.

AppDefinition entity

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 AppDefinitions the organization owner, admin or developer role is required.

Hosting

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 localhost.

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 http://localhost:1234.

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 src URL.

The app configuration screen is the most complex element of a Contentful 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.