Was this page helpful?

Manage UI Extensions via the CLI

Extensions are built and managed within a Contentful space through the Content Management APIs extension endpoint. To make it more convenient, the Create Contentful Extension CLI supports managing the extensions.

This article explains how to create and deploy a UI Extension from scratch using this tool.

Create a new UI Extension

To get started, generate your first extension using create-contentful-extension:

npx @contentful/create-contentful-extension my-first-extension

It will ask you what type of extension you want to create:

  • Field extension
  • Sidebar extension

Then npm will install all required development and production dependencies and create a directory called my-first-extension inside the current folder.

├── node_modules
├── .babelrc
├── .gitignore
├── package.json
├── extension.json
└── src
    ├── index.html
    ├── index.js
    └── index.css

Once the installation is done, you can open your project folder:

cd my-first-extension

Local development

To start development run the following commands in the newly created my-first-extension folder:

npm run login

It starts a new session with our CLI. As the CLI tool uses our Content Management API, you need to have a CMA access token to use all the commands.

Once you're successfully logged in, you can run the following command:

npm run start

First it asks in which space you'd like to install the extension, then it starts the development server and deploys the extension in development mode to the selected space. The extension will automatically reload if you make changes to the code.

Note: As Contentful runs in an HTTPS environment, temporarily disable the security checks in the browser. For example, "Load unsafe scripts" in Chrome.

Uploading a UI Extension to Contentful

When development is done, you need to install your extention to a space in production mode. To do so run the following command in your extension folder:

npm run deploy

It correctly bundles all extension dependencies in production mode and optimizes the build for the best performance, then it uploads build version of extension to a selected space.

Configuring a field to use an extension

Refer the section Assigning UI Extensions to a Field to assign the extension to the particular field where it needs to be used.

Managing UI Extensions via contentful-cli

contentful extension is composed of the following five subcommands that are used to manage extensions:

  • Create - Creates an extension for the first time.

contentful extension create [options]

  • Update - Modifies an existing extension.

contentful extension update [options]

  • Delete - Permanently deletes an extension.

contentful extension delete [options]

  • Read - Reads the extension payload from Contentful.

contentful extension read [options]

  • List - Lists all the extensions created for the given space.

contentful extension list [options]

To learn how these commands work in CLI, refer the CLI documentation or use inline help of the CLI:

contentful extension --help

Version Locking

Contentful uses optimistic locking to avoid accidental non-idempotent operations such as update or delete.

While using the update and delete subcommands, it is mandatory to specify the version of the extension using the --version option. Alternatively, the --force option can be used that instructs the CLI to use the latest version of the extension.

Note: Using `--force` option might lead to accidental overwrites if multiple users are working on the same.

Programmatic Usage

To manage an extension programmatically, refer the Content Management SDKs.

Next steps

Not what you’re looking for? Try our FAQ.