Contentful allows customers to customize and tailor the UI using custom made extensions. Extensions have to be uploaded to Contentful in order to be able to use them in the UI.
This repo hosts
contentful-extension a Command Line Tool (CLI) developed to simplify the management tasks associated with custom extensions. With the CLI you can:
- Create extensions
- Update existing extensions
- Read extensions
- Delete extensions
npm install -g contentful-extension-cli
contentful-extension is composed of 4 subcommands that you can use to manage the extensions.
create an extension
contentful-extension create [options]
Use this subcommand to create the extension for the first time. Succesive modifications made to the extension will be have to be using the
read an extension
contentful-extension read [options]
Use this subcommand to read the extension payload from Contentful. With this subcommand you can also list all the extensions in one space.
update an extension
contentful-extension update [options]
Use this subcommand to modify an existing extension.
delete an extension
contentful-extension delete [options]
Use this subcommand to pertmanently delete an extension from Contentful.
For a full list of all the options available on every subcommand use the
The following sections describe a series of concepts around the extensions and how the CLI deals with them.
The following table describes the properties that can be set on an extension.
|fieldTypes||yes||Array<String> *||Field types where an extension can be used|
|src||**||String||URL where the root HTML document of the extension can be found|
|srcdoc||**||String||Path to the local extension HTML document|
|sidebar||no||Boolean||Controls the location of the extension. If
* Valid field types are:
** One of
srcdoc have to be present
src property, an extension is considered 3rd party hosted. Relative links in the root HTML document are supported as expected.
srcdoc property, an extension is considered internally hosted. A file being pointed by the
srcdoc property will be loaded and uploaded as a string to Contentful. All local dependencies have to be manually inlined into the file. The command line tool does not take care of link resolving and inlining of referenced local resources. The maximal size of a file used with the
srcdoc property is 200kB. Use HTML minifier with
minifyJS option and use CDN sources for libraries that your extension is depending on.
If a relative value of
srcdoc property is used, the path is resolved from a directory in which the descriptor file is placed or a working directory when using the
--srcdoc command line option.
src property when you want to be as flexible as possible with your development and deployment process. Use
srcdoc property if you don't want to host anything on your own and can accept the drawbacks (need for a non-standard build, filesize limitation).
Specifying extension properties
Subcommands that create of modify extensions (
update) accept the properties for the extension in two forms: command line options or a JSON file.
Command line options
For every property in the extension there's a corresponding long option with the same name. So for example, there's a
name property and so a
--name option too.
contentful-extension create --space-id 123 --name foo --src foo.com/extension
Note that camelcased property names like
fieldTypes are hyphenated (
Descriptor files are JSON files that contain the values that will be sent to the API to create the extension. By default the CLI will look in the current working directory for a descriptor file called
extension.json. Another file can be used witht the
A descriptor file can contain:
- All the extension properties (
src, ...). Please note that the
srcdocproperty has to be a path to a file containing the extension HTML document.
idproperty. Including the
idin the descriptor file means that you won't have to use the
--idoption when creating or updating an extension.
All the properties included in a descriptor file can be overriden by its counterpart command line options. This means that, for example, a
--name bar option will take precedence over the
name property in the descriptor file. Following is an example were the usage of descriptor files is explained:
Assuming that there's an
extension.json file in the directory where the CLI is run and that's its contents are:
The following command
contentful-extension create --space-id 123 --name bar
Will create the following extension. Note that the
bar and that the
Extensions are managed via the Contentful Management API (CMA).
You will therefore need to provide a valid access token in the
CONTENTFUL_MANAGEMENT_ACCESS_TOKEN environment variable.
Our documentation describes how to obtain a token.
Contentful API use optimistic locking to ensure that accidental non-idemptotent operations (
delete) can't happen.
This means that the CLI needs to know the current version of the extension when using the
delete subcommands. On these case you have to specify the version of the extension using the
If you don't want to use the
--version option on every update or deletion, the alternative is to use
--force. When the
--force option is present the CLI will automatically use the latest version of the extension. Be aware that using
--force option might lead to accidental overwrites if multiple people are working on the same extension.
You can also use CLI's methods with a programmatic interface (for example in your build process). A client can be created simply by requiring
contentful-extension-cli npm package:
const cli = ;const client = cli;// getting an array of all extensions in the spaceclient;// getting a single extensionclient;// save method takes an object of extension properties described aboveclient;// the only difference is that srcdoc is a HTML document string// instead of a path (so it can be fed with custom build data)client;// if extension was saved, a result of the get method call will contain// version that has to be supplied to the consecutive save callclient;// delete method also requires a version numberclient;