Do this with AI
Install the developer-hub-app-architect skill from 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 first.
Manifest and UI locations
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:
csdx plugins:install @contentstack/apps-cli
csdx auth:loginThe plugin uses your login session. Management tokens do not work here, so log in first.
Now create the app:
csdx app:create --name seo-helper --app-type stackThe 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.
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:
{
"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 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:
npm run devThe 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 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.
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.