contentful-ui-extensions-sdk

App SDK

The App SDK (formerly known as UI Extensions SDK) is a JavaScript library that allows developers to create custom Contentful Apps for the Contentful Web App. Every Contentful App has to include the library in its source.

Resources

• App SDK reference
• App Framework general documentation
• UI Extensions general documentation
• Contentful Apps Management HTTP API reference
• Contentful Apps FAQ
• Contentful Apps repository
• Contentful Marketplace
• Contentful Changelog
• Forma 36: The Contentful Design System
• Forma 36 guide for Contentful Apps
• create-contentful-app - CLI tool for developing apps without the hassle of managing build configurations
• contentful-ui-extensions-sdk at npm

Getting help

Technical questions, feedback or feature request can be provided directly through the Github issues for this repository. However, if you are a paying customer or at any point business sensitive information needs to be discussed, then the conversation should be handled via our support system.

Development

Publishing

A new package version is automatically published to npm using semantic-release.

To manually publish the package, run npm run publish-all.

This repository is published as two packages with identical data. We recommend using @contentful/app-sdk.

• @contentful/app-sdk
• contentful-ui-extensions-sdk

Canary releases

This package has two main development streams: latest and canary.

The default and stable releases are always published under the latest tag (as per npm convention). The release under the canary tag is to be considered unstable and potentially breaking. You should not rely on it in production.

File Structure

docs

Former home of the documentation and reference for this library. This is now deprecated and you should use links above.

lib

Includes the files constituting the SDK and the associated types.

Top level files are split by feature. Most of them map 1-to-1 to an API (keep reading for the outliers). When APIs are considered too small to be in a separate file, they are part of the api file.

• channel and signal abstract the communication between an App and the host;
• locations exports available location where you can run App;
• initialize creates an initializer to start an App within Contentful's App Framework.

All the typings are in the types folder and they map 1-to-1 APIs, when they make sense. The entities file maps Contentful entities in TypeScript. utils includes utility types, meant to save on characters to type.

scripts

Includes utility tools for maintainers.

test

Includes integration tests (run by Cypress) and unit tests (run by mocha)

Changelog

4.0.0 (2021-10-05)

This major release of the Contentful App SDK provides two great features to make app development for Contentful even easier.

Contentful Management API Adapter

You can now use the contentful-management library within apps. This gives you access to a huge load of APIs that were previously not available. Also, you can reuse existing code utilising the contentful-management library which makes it easier to convert your custom Contentful scripts to convenient apps.

After installing the library, a new client can be created using the cmaAdapter which is exposed by the App SDK. There is no need to deal with authentication and tokens.

import { createClient } from 'contentful-management'

const nestedClient = createClient({ apiAdapter: sdk.cmaAdapter })

const cma = createClient(
  { apiAdapter: sdk.cmaAdapter },
  {
    type: 'plain',
    defaults: {
      environmentId: sdk.ids.environment,
      spaceId: sdk.ids.space,
    },
  },
)

Please note that not all methods are available. You can only use methods that access entities within the app’s space environment.

Deprecation of Space API

The Space API (sdk.space) is deprecated and will be removed in a future major update of the App SDK. We recommend using the new CMA Adapters to replace existing Space API functionality.

Typings revamp

In the previous version of the App SDK app developers sometimes struggled with our provided types. For version 4 we took the opportunity to revamp and significantly improve the types of the whole library. These changes are likely to break existing TypeScript apps as we are more specific about each property and also changed the usage of generics on API methods. The new types of the App SDK now align with the types of the contentful-management library. To get the best development experience, you need to install contentful-management as a separate dependency.

npm install contentful-management

We do not include this dependency by default to keep your dependency tree clean and ensure small bundle sizes and short build times.