> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# UI extensions - File structure

> File structure of a UI Extension | Using an HTML file to hold the code and JSON file for supported field types

> **Info**
>
> **Use the [App Framework](/extensibility/app-framework) for any new projects.** We recommend creating apps instead of UI extensions. [Read the app FAQ to learn why](https://www.contentful.com/help/contentful-app-framework-faq/).

The minimal file structure of extensions consists of two files:

* An HTML file (e.g. `index.html`) which holds the code of the extension
* A JSON file (e.g. `extension.json`) which describes the extension's properties such as `name` or the supported field types

Let's take a closer look at these files to understand what they do.

## Source code: index.html

The `index.html` file is the building block for an extension and it is embedded into the Contentful entry editor as an `<iframe>`.

The `index.html` includes the following:

* the markup code and the logic.

* reference to the App SDK which,

  * enables the extension to communicate with the Contentful web app.

  * exposes the `contentfulApp.init()` method. This is the main entry point for all the extension-related code.

Following is an example of the `contentfulApp.init()` method:

```javascript
window.contentfulApp.init(function (extension) {
  var value = extension.field.getValue();
  extension.field.setValue('Hello world!');
});
```

```HTML
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8"/>
    <title>Sample Editor Extension</title>
    <script src="https://cdn.jsdelivr.net/npm/@contentful/app-sdk@4"></script>
  </head>
  <body>
    <div id="content"></div>
    <script type="text/javascript">
      window.contentfulApp.init(function (extension) {
        var value = extension.field.getValue()
        extension.field.setValue("Hello world!")
      })
    </script>
  </body>
</html>
```

## Descriptor file: extension.json

The `extension.json` file, also known as the **Descriptor file**, is used to describe the properties of an extension. Although this file is optional, it is recommended to create it. The Contentful CLI is supporting descriptor files. Descriptor files should be committed to version control next to the source code of the extension as they describe the configuration fo the extension.

The following table describes the properties that can be set on an extension.

| Property     | Required                               | Type              | Description                                                                                     |
| ------------ | -------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| `id`         | yes, if omitted it gets auto-generated | `String`          | Extension id                                                                                    |
| `name`       | yes                                    | `String`          | Extension name                                                                                  |
| `fieldTypes` | no                                     | `Array<String>`\* | The [field types of a content type](/concepts/data-model#fields) where an extension can be used |
| `src`        | `src` or `srcdoc` is required          | `String`          | URL where the root HTML document of the extension can be found                                  |
| `srcdoc`     | `src` or `srcdoc` is required          | `String`          | Path to the local extension HTML document                                                       |
| `sidebar`    | no                                     | `Boolean`         | Controls the location of the extension. If `true` it will be rendered on the sidebar            |

\* Valid field types are: `Symbol`, `Symbols`, `Text`, `Integer`, `Number`, `Date`, `Boolean`, `Object`, `Entry`, `Entries`, `Asset`, `Assets`.

The following is an example of an `extension.json` file:

```json
{
  "id": "extension",
  "name": "My first extension",
  "srcdoc": "./app.html",
  "fieldTypes": ["Text"]
}
```

## Next steps

* [UI Extensions - Parameters.](/extensibility/ui-extensions/parameters/)