---
title: "Manifest and UI locations"
url: "https://developers.contentstack.com/guides/build-your-first-developer-hub-app/manifest-and-ui-locations"
type: "guide_chapter"
level: "intermediate"
intent: "build"
outcome: "You have a registered stack app, a local copy of the boilerplate, and a manifest with the UI locations your app needs."
prerequisites:
  - "Contentstack CLI 2.x installed and logged in with csdx auth:login"
  - "Node.js 22 or later"
  - "Permission to create apps in your organization"
next:
  - "https://developers.contentstack.com/guides/build-your-first-developer-hub-app/app-sdk-v2-essentials"
tags:
  - "sdk"
  - "cli"
  - "react"
authors:
  - "Tim Benniks"
published: "2026-11-15T10:19:03.271Z"
updated: "2026-11-15T10:55:07.544Z"
---

# Manifest and UI locations

- **Authors:** Tim Benniks
- **Published:** 2026-11-15T10:19:03.271Z
- **Updated:** 2026-11-15T10:55:07.544Z
- **Level:** Intermediate
- **Intent:** Build
- **Tags:** sdk, cli, react

---

Every Developer Hub app starts with two things: an entry in Developer Hub that holds the manifest, and a code base that renders each location. You can create both by hand in the Developer Hub UI, but the apps CLI plugin does it in one command and gives you a working React boilerplate.

This chapter sets up that scaffold and explains what the manifest controls, so the rest of the guide has something real to build on.

## What you'll learn

- How to scaffold an app with csdx app:create


- What the app manifest contains


- Which UI locations exist and what each one is for


- How location paths map to routes in your app


- How to run the app locally inside Contentstack



## Scaffold the app with the CLI

The apps CLI is an opt-in plugin for the Contentstack CLI. Install it once:

```bash
csdx plugins:install @contentstack/apps-cli
csdx auth:login
```

The plugin uses your login session. Management tokens do not work here, so log in first.

Now create the app:

```bash
csdx app:create --name seo-helper --app-type stack
```

The command asks which boilerplate to use (App Boilerplate, DAM App Boilerplate or Ecommerce App Boilerplate), registers the app in Developer Hub, downloads the boilerplate into a folder named after the app, writes a manifest.json into it, and runs npm install. App names are 3 to 20 characters and unique within an organization.

Pick App Boilerplate for this guide. It is React, TypeScript and Vite with every stack location already wired up.

If you skip the GitHub download prompt, the app is still registered but no local manifest.json is written. Run the command again or create the folder from the [boilerplate repository](https://github.com/contentstack/marketplace-app-boilerplate).

## Understand the manifest

Contentstack concept: The app manifest is the declarative definition of your app. It holds identity, UI locations, OAuth settings, webhooks, hosting and Advanced Settings.

You edit most of it through the tabs in Developer Hub. The App Manifest tab shows the JSON, and you can export or edit it there. The ui_location part looks like this:

```json
{
  "ui_location": {
    "signed": true,
    "base_url": "http://localhost:3000",
    "locations": [
      {
        "type": "cs.cm.stack.custom_field",
        "meta": [
          {
            "name": "SEO score",
            "path": "/custom-field",
            "data_type": "json",
            "signed": true,
            "enabled": true
          }
        ]
      },
      {
        "type": "cs.cm.stack.sidebar",
        "meta": [
          { "name": "SEO checks", "path": "/entry-sidebar", "signed": true }
        ]
      },
      {
        "type": "cs.cm.stack.config",
        "meta": [{ "path": "/app-configuration", "signed": true }]
      }
    ]
  }
}
```

A few fields carry most of the weight:

- type is the location identifier. There is one entry per type.


- path is appended to the hosting URL to build the iframe src.


- signed makes Contentstack add a short-lived JWT to the iframe URL, which [chapter 4](/guides/build-your-first-developer-hub-app/hosting-and-going-live) shows you how to verify. Set it on each meta entry, not only at the top level.


- data_type is required for custom fields. It decides what kind of value the field stores: text, number, isodate, boolean, json, reference, file or asset.



base_url is overwritten by the URL you set in the Hosting tab, so treat the Hosting tab as the source of truth.

## Choose your UI locations

A UI location is an extension point in the Contentstack UI. Each one renders your app in an iframe, except JSON RTE plugins, which load as a script inside the editor.

Location

Manifest type

Use it for

App configuration

cs.cm.stack.config

Settings and API keys per installation

Custom field

cs.cm.stack.custom_field

A field type in a content type, such as a product picker

Entry sidebar

cs.cm.stack.sidebar

Tools that act on the open entry, such as SEO checks

Stack dashboard

cs.cm.stack.dashboard

A widget on the stack dashboard

Asset sidebar

cs.cm.stack.asset_sidebar

Tools for the open asset, such as image metadata

Full page

cs.cm.stack.full_page

A standalone screen inside the stack

Field modifier

cs.cm.stack.field_modifier

Acting on an existing field in the entry editor

JSON RTE

cs.cm.stack.rte

Buttons and plugins in the JSON Rich Text Editor

Organization config

cs.org.config

Settings for an organization app

Organization apps can use only cs.org.config and the organization-level full page. Everything else needs a stack app.

Start small. Declare only the locations you build. The boilerplate wires up all of them, and every unused location is one more screen that installers see and one more route you have to keep working. A first app usually needs a config page plus one location where editors do the work.

## Map paths to routes

The boilerplate is one single-page app with a route per location: /custom-field, /entry-sidebar, /app-configuration, /stack-dashboard, /asset-sidebar, /full-page, /field-modifier and more. Each route is lazy-loaded, so a sidebar does not download the custom field code.

When you remove a location from the manifest, remove its route as well. When you add one, make sure the path matches a route exactly. A mismatch loads your app's 404 inside the Contentstack UI, which is easy to miss if you only test one location.

## Run it inside Contentstack

Start the dev server:

```bash
npm run dev
```

The boilerplate serves on http://localhost:3000. In Developer Hub, open your app, go to the Hosting tab, pick Custom Hosting and enter that URL. Then click Install App, pick a test stack, and open an entry. Your locations now render from your machine, and code changes hot-reload.

Use a tunnel such as ngrok if someone else needs to see the app from their own browser.

## Where people get confused

Code changes and manifest changes behave differently. Code at your hosting URL updates for every installation as soon as you deploy it. Manifest changes, such as a new location or a new webhook event, create a new version. Existing installations see that version as an available update. They do not switch over on their own.

Locations also need permissions. The UI Locations tab has an App Permissions section, and by default no permissions are selected. If your app calls Contentstack APIs, grant only the scopes those calls need. [Chapter 3](/guides/build-your-first-developer-hub-app/oauth-and-machine-to-machine-apps) covers scopes in detail.

## Key takeaways

- Run csdx plugins:install @contentstack/apps-cli, then csdx app:create to register an app and scaffold the boilerplate in one step.


- The manifest declares locations, OAuth, webhooks, hosting and Advanced Settings.


- Each location's path is appended to the hosting URL. Keep paths and routes in sync.


- Set signed: true on each meta entry that handles data.


- Declare only the locations you build, and remember that manifest changes become updates for existing installations.





---

## Do this with AI

Install the developer-hub-app-architect skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the DeveloperHub profile in MCP Profile Hub. Then ask your agent:

> List the apps in my organization with their UI locations, and check whether the manifest of the app I am building duplicates a location another app already covers.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### What is the difference between a stack app and an organization app?

A stack app installs into a stack and can use stack locations such as custom fields and sidebars. An organization app installs at the organization level and only uses the organization config and global full page locations.

### Does adding a UI location create a new app version?

Yes. Saving a change to UI locations, webhooks, OAuth or hosting creates a new manifest version. Code changes at your hosting URL are not versioned.

### Can one app use several UI locations?

Yes. One app can declare many locations, and they all load the same hosted app on different paths.



---

## Chapter Navigation

**← Previous:** [Build your first Developer Hub app](https://developers.contentstack.com/guides/build-your-first-developer-hub-app)

**Next →:** [App SDK v2 essentials](https://developers.contentstack.com/guides/build-your-first-developer-hub-app/app-sdk-v2-essentials)
