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

# Create Contentful App

> Creating a new app with create-contentful-app | AppDefinition | Local development | Deploying with Contentful | Programmatic app management

Apps allow you to embed single page applications inside the Contentful web app and extend the Contentful experience. To make the process of creating a new app simpler, the [`create-contentful-app` CLI](https://github.com/contentful/create-contentful-app) supports creating an app template, creating an [`AppDefinition`](/extensibility/app-framework/app-definition), and gives instructions on how to install the app into a space environment.

This article explains how to create and develop an app from scratch using `create-contentful-app`.

## Prerequisites

In order to use this command line tool, you'll need [Node.js version 14 or newer](https://nodejs.org/en/) installed on your machine.
You will also need a Contentful account with an organization management role. Organization management roles are owners, admins or developers.

## Create a new app

To get started, run `create-contentful-app` in your command line:

```bash
npx create-contentful-app my-first-app
```

This command generates your app project and installs all required dependencies.

<pre>
  public
  └── index.html
  src
  ├── components
  │   └── LocalhostWarning.tsx
  ├── locations
  │   ├── ConfigScreen.spec.tsx
  │   ├── ConfigScreen.tsx
  │   ├── Dialog.spec.tsx
  │   ├── Dialog.tsx
  │   ├── EntryEditor.spec.tsx
  │   ├── EntryEditor.tsx
  │   ├── Field.spec.tsx
  │   ├── Field.tsx
  │   ├── Home.spec.tsx
  │   ├── Home.tsx
  │   ├── Page.spec.tsx
  │   ├── Page.tsx
  │   ├── Sidebar.spec.tsx
  │   └── Sidebar.tsx
  ├── App.tsx
  ├── index.tsx
  ├── react-app-env.d.ts
  └── setupTests.ts
  .gitignore
  README.md
  package.json
  package-lock.json
</pre>

When the command finishes it will have created a new directory called `my-first-app`.

**Note:** The created `package.json` contains all packages needed for creating your app together with a field called `homepage` referring to the local directory.
What this does is, all the links in your build will be relative to the location of the `index.html`.
To find out more you can read [here](https://create-react-app.dev/docs/deployment/#serving-the-same-build-from-different-paths).

### Options

By default, `create-contentful-app` creates a Contentful app using [TypeScript](https://www.typescriptlang.org/). If you prefer to build your app using vanilla JavaScript, instead run `npx create-contentful-app -js my-first-app`.

To create your new app using one of Contentful's [public examples](https://github.com/contentful/apps/tree/master/examples), use the `--example` option followed by the example name.

To use [Yarn](https://yarnpkg.com/) instead of [npm](https://www.npmjs.com/), you can pass the `--yarn` flag.

To learn more about what `create-contentful-app` is capable of, run:

```bash
npx create-contentful-app --help
```

## Creating an `AppDefinition`

You need to create an [`AppDefinition`](/extensibility/app-framework/app-definition) for your app in order to use it on Contentful. This can either be done through the Contentful web application or through `create-contentful-app`.
To do this using `create-contentful-app`, open your project folder and configure your app:

```bash
cd my-first-app
npm run create-app-definition
```

Running the `create-app-definition` command will walk you through the process of configuring your app, and creating an `AppDefinition`. If necessary the command will also walk you through the process of authenticating with Contentful.
The configuration created in this step can easily be changed by following [this link](https://app.contentful.com/deeplink?link=app-definition).

### Local development

Once the configuration is complete, run the app:

```bash
npm start
```

This command starts the development server and will walk you through installing your app into a Contentful space environment. 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, enable "Load unsafe scripts" in Chrome.

## Deploy with Contentful

### Building an app

Before deploying your app you will need to build it. Do this by running `npm run build`, this will create a build folder.

### Uploading an app

Now you can upload your build to Contentful with the following command:

```bash
npm run upload
```

The command prompts you for some required options to upload the build folder and to create a bundle. Alternatively, if you want to run it in a CI pipeline, you can run it with the required options as arguments:

```bash
npm run upload --ci \
     --organization-id some-org-id \
     --definition-id some-app-def-id \
     --token your-contentful-access-token
```

**Note:** You can also pass all arguments in interactive mode without the `--ci` option to skip the prompts. Passing `--ci` just makes the command fail when the mandatory arguments are missing.

If you have already set all options as environment variables, you can also run the following command, which automatically takes your defined environment variables as arguments:

```bash
npm run upload-ci
```

**Options:**

| Argument            | Description                                                            | Environment Variable      |
| ------------------- | ---------------------------------------------------------------------- | ------------------------- |
| `--organization-id` | The ID of your organization                                            | `CONTENTFUL_ORG_ID`       |
| `--definition-id`   | The ID of the app to which to add the bundle                           | `CONTENTFUL_APP_DEF_ID`   |
| `--token`           | A personal [access token](/references/content-management-api/overview) | `CONTENTFUL_ACCESS_TOKEN` |
| `--skip-activation` | (optional) Boolean flag to skip the automatic activation of the bundle | -                         |

If the upload was successful, the uploaded bundle will be activated right away and deployed to your defined `AppDefinition`. If you do not want to activate it automatically,
you can skip it with the `--skip-activation` option in interactive and non-interactive mode.

#### Activating a bundle

To make your app serve a specific bundle, you can activate it manually by running the activate command:

```bash
npm run activate
```

When you run this command, you will be guided through some questions to get all the information to activate your bundle.
Similar to upload, you can also run this command with passing all options as arguments:

```bash
npm run activate --ci \
     --bundle-id some-bundle-id \
     --organization-id some-org-id \
     --definition-id some-app-def-id \
     --token your-contentful-access-token
```

**Note:** You can also pass all arguments in interactive mode without the `--ci` option to skip the prompts. Passing `--ci` just makes the command fail when the mandatory arguments are missing.

**Options:**

| Argument            | Description                                                            | Environment Variable      |
| ------------------- | ---------------------------------------------------------------------- | ------------------------- |
| `--bundle-id`       | The ID of the bundle you want to activate                              | -                         |
| `--organization-id` | The ID of your organization                                            | `CONTENTFUL_ORG_ID`       |
| `--definition-id`   | The ID of the app to which to add the bundle                           | `CONTENTFUL_APP_DEF_ID`   |
| `--token`           | A personal [access token](/references/content-management-api/overview) | `CONTENTFUL_ACCESS_TOKEN` |

## Programmatic app management

To manage an app programmatically, refer the [Content Management SDKs](/references/content-management-api/overview).

## Tracking

We gather depersonalized usage data of our CLI tools in order to improve experience. If you do not want your data to be gathered, you can opt out by providing an env variable `DISABLE_ANALYTICS` set to any value:

```bash
DISABLE_ANALYTICS=true npx create-contentful-app
```

## Next steps

* [Using Forma 36 in an app](/extensibility/ui-extensions/component-library/)