Contentful Custom App From Scratch
Use this skill to turn a customer app idea into a small, locally testable
Contentful App Framework implementation.
Default to the user's own repository, Contentful organization, and app delivery
workflow unless they explicitly choose another destination.
Public Contentful Marketplace apps and Contentful's public apps repository
(https://github.com/contentful/apps) can be useful references for mature App
Framework patterns, UX conventions, and configuration flows. Use them as
examples to adapt, not as required repo structure or publication process.
Working Style
- Start with the app's job, primary users, affected content model, and target
Contentful surface before writing code.
- Ask only for information that changes the architecture or prevents a wrong
build.
- Prefer the smallest version that proves the value in a non-production space.
- Ground capability decisions in official App Framework docs and the current
project structure.
- Keep user-owned secrets, tokens, and production content out of generated code,
logs, and examples.
Workflow
1. Create the Implementation Brief
Capture a short brief before scaffolding:
- app concept in one sentence,
- target users and the workflow they need to improve,
- Contentful locations needed for v1,
- content types, fields, locales, and environments involved,
- external systems, authentication, or APIs involved,
- expected installation and configuration model,
- must-have v1 behavior,
- assumptions and non-goals,
- validation plan for local and sandbox testing.
If the idea is still broad, propose 2-3 feasible v1 options and recommend the
smallest useful one.
For planning details, use App planning.
2. Choose the App Shape
Choose locations by user workflow:
- Use
app-config when the app needs installation-time setup.
- Use
entry-sidebar for entry-level context, status, helper actions, and
lightweight insights.
- Use
entry-field to replace or enhance a field's editing experience.
- Use
dialog for focused picker, confirmation, or multi-step flows launched
from another location.
- Use
page or home for dashboards, bulk tools, onboarding, or full-screen
operational workflows.
- Use
entry-editor only when replacing or heavily extending the full entry
editing experience is worth the maintenance cost.
- Use App Actions or Functions only when the app needs asynchronous behavior,
server-side execution, verified inbound requests, event handling, or access to
secret values outside the browser.
If sensitive credentials are required, model them as secret installation
parameters and consume raw values only in a backend or Function-backed path.
3. Inspect or Scaffold the Project
If the user already has a repo:
- Inspect
package.json, app-related docs, existing app locations, build
scripts, tests, and style conventions.
- Reuse the repo's framework, package manager, lint/test setup, and component
patterns.
- Identify whether the app already uses
@contentful/app-sdk,
@contentful/react-apps-toolkit, @contentful/f36-components, or
contentful-management.
If the user does not have a repo:
- Scaffold with
npx create-contentful-app@latest <app-name>.
- Prefer TypeScript unless the user requests JavaScript.
- Keep the first scaffold close to the generated project until the local app is
wired into Contentful and verified.
4. Build in Contentful-Native Style
- Use the App SDK or React Apps Toolkit to access the current location SDK.
- Use Forma 36 components for Contentful web app UI. Always check if Forma 36 has a similar component before attempting to build something custom.
- Keep UI dense, clear, and editor-friendly; avoid marketing layouts inside the
Contentful web app.
- Include loading, empty, permission, and error states when they affect the main
workflow.
- Keep field and entry writes explicit, reversible where possible, and easy for
editors to understand.
- When runtime locations need app configuration, read installation parameters
from
sdk.parameters.installation. Do not fetch app installation records
through CMA from mount effects, render paths, hooks, or user interactions just
to retrieve configured parameters.
- Avoid broad abstractions until the app has more than one real usage path.
- Do not expose management tokens, API keys, or third-party credentials in
browser code.
5. Wire the Local App into Contentful
Create or update the app definition in a development organization or sandbox:
- set the frontend URL to the local dev server, commonly
http://localhost:3000,
- select only the locations implemented in v1,
- define required installation or instance parameters,
- install the app into a non-production space or environment,
- assign the app to the relevant content types, fields, sidebar, home page, or
page location,
- seed minimal test content when needed.
For local test and handoff steps, use
Repository and validation.
6. Verify Before Handoff
Run the closest meaningful checks available in the user's project:
- package install check when dependencies changed,
- typecheck and lint,
- unit or component tests,
- production build,
- local dev server smoke test,
- manual Contentful web app flow in a non-production space.
rg -n "appInstallation\\.(getForOrganization|get)\\(|getForOrganization"
over the app source when runtime code reads installation parameters, with any
remaining CMA app-installation call explained.
Do not claim the app works unless you ran the relevant validation or clearly
state what could not be run.
7. Hand Off the Result
End with:
- what was built,
- how to run it locally,
- how to install or assign it in Contentful,
- validation performed,
- remaining assumptions, limitations, or credentials needed,
- suggested next iteration.
Related Skills
contentful-custom-app-enhancement - improve or debug an existing custom app.
contentful-api - concrete CMA, CDA, CPA, Images API, and GraphQL examples.
contentful-migration - content model migration scripts.
contentful-guide - Contentful concepts and API routing.
1---
2name: contentful-custom-app-from-scratch
3description: >-
4 Design, scaffold, build, and validate a new Contentful App Framework custom
5 app for a customer's own repository or workspace. Use when users want to
6 create a custom app from an idea, choose App Framework locations, build a
7 sidebar app, field editor app, page app, dialog, configuration screen, App
8 Action, or Function-backed app, scaffold with create-contentful-app, or make a
9 locally testable app for an organization-specific Contentful workflow. Also
10 triggers on "build a Contentful app", "custom app from scratch", "App
11 Framework app", "sidebar app", "field editor app", "page app", "app action",
12 and "app function". Not for generic Contentful API examples (contentful-api),
13 content model migrations (contentful-migration), or website integration
14 (contentful-nextjs).
15license: MIT
16metadata:
17 source: https://skillmd.com/skills/contentful/contentful-custom-app-from-scratch
18 author: contentful
19 version: "2.0.0"
20allowed-tools: mcp__contentful-mcp__* mcp__plugin_contentful_contentful-mcp__*
21---
22
23# Contentful Custom App From Scratch
24
25Use this skill to turn a customer app idea into a small, locally testable
26Contentful App Framework implementation.
27
28Default to the user's own repository, Contentful organization, and app delivery
29workflow unless they explicitly choose another destination.
30
31Public Contentful Marketplace apps and Contentful's public apps repository
32(`https://github.com/contentful/apps`) can be useful references for mature App
33Framework patterns, UX conventions, and configuration flows. Use them as
34examples to adapt, not as required repo structure or publication process.
35
36## Working Style
37
38- Start with the app's job, primary users, affected content model, and target
39 Contentful surface before writing code.
40- Ask only for information that changes the architecture or prevents a wrong
41 build.
42- Prefer the smallest version that proves the value in a non-production space.
43- Ground capability decisions in official App Framework docs and the current
44 project structure.
45- Keep user-owned secrets, tokens, and production content out of generated code,
46 logs, and examples.
47
48## Workflow
49
50### 1. Create the Implementation Brief
51
52Capture a short brief before scaffolding:
53
54- app concept in one sentence,
55- target users and the workflow they need to improve,
56- Contentful locations needed for v1,
57- content types, fields, locales, and environments involved,
58- external systems, authentication, or APIs involved,
59- expected installation and configuration model,
60- must-have v1 behavior,
61- assumptions and non-goals,
62- validation plan for local and sandbox testing.
63
64If the idea is still broad, propose 2-3 feasible v1 options and recommend the
65smallest useful one.
66
67For planning details, use [App planning](references/app-planning.md).
68
69### 2. Choose the App Shape
70
71Choose locations by user workflow:
72
73- Use `app-config` when the app needs installation-time setup.
74- Use `entry-sidebar` for entry-level context, status, helper actions, and
75 lightweight insights.
76- Use `entry-field` to replace or enhance a field's editing experience.
77- Use `dialog` for focused picker, confirmation, or multi-step flows launched
78 from another location.
79- Use `page` or `home` for dashboards, bulk tools, onboarding, or full-screen
80 operational workflows.
81- Use `entry-editor` only when replacing or heavily extending the full entry
82 editing experience is worth the maintenance cost.
83- Use App Actions or Functions only when the app needs asynchronous behavior,
84 server-side execution, verified inbound requests, event handling, or access to
85 secret values outside the browser.
86
87If sensitive credentials are required, model them as secret installation
88parameters and consume raw values only in a backend or Function-backed path.
89
90### 3. Inspect or Scaffold the Project
91
92If the user already has a repo:
93
941. Inspect `package.json`, app-related docs, existing app locations, build
95 scripts, tests, and style conventions.
962. Reuse the repo's framework, package manager, lint/test setup, and component
97 patterns.
983. Identify whether the app already uses `@contentful/app-sdk`,
99 `@contentful/react-apps-toolkit`, `@contentful/f36-components`, or
100 `contentful-management`.
101
102If the user does not have a repo:
103
1041. Scaffold with `npx create-contentful-app@latest <app-name>`.
1052. Prefer TypeScript unless the user requests JavaScript.
1063. Keep the first scaffold close to the generated project until the local app is
107 wired into Contentful and verified.
108
109### 4. Build in Contentful-Native Style
110
111- Use the App SDK or React Apps Toolkit to access the current location SDK.
112- Use Forma 36 components for Contentful web app UI. Always check if Forma 36 has a similar component before attempting to build something custom.
113- Keep UI dense, clear, and editor-friendly; avoid marketing layouts inside the
114 Contentful web app.
115- Include loading, empty, permission, and error states when they affect the main
116 workflow.
117- Keep field and entry writes explicit, reversible where possible, and easy for
118 editors to understand.
119- When runtime locations need app configuration, read installation parameters
120 from `sdk.parameters.installation`. Do not fetch app installation records
121 through CMA from mount effects, render paths, hooks, or user interactions just
122 to retrieve configured parameters.
123- Avoid broad abstractions until the app has more than one real usage path.
124- Do not expose management tokens, API keys, or third-party credentials in
125 browser code.
126
127### 5. Wire the Local App into Contentful
128
129Create or update the app definition in a development organization or sandbox:
130
131- set the frontend URL to the local dev server, commonly
132 `http://localhost:3000`,
133- select only the locations implemented in v1,
134- define required installation or instance parameters,
135- install the app into a non-production space or environment,
136- assign the app to the relevant content types, fields, sidebar, home page, or
137 page location,
138- seed minimal test content when needed.
139
140For local test and handoff steps, use
141[Repository and validation](references/repo-and-validation.md).
142
143### 6. Verify Before Handoff
144
145Run the closest meaningful checks available in the user's project:
146
147- package install check when dependencies changed,
148- typecheck and lint,
149- unit or component tests,
150- production build,
151- local dev server smoke test,
152- manual Contentful web app flow in a non-production space.
153- `rg -n "appInstallation\\.(getForOrganization|get)\\(|getForOrganization"`
154 over the app source when runtime code reads installation parameters, with any
155 remaining CMA app-installation call explained.
156
157Do not claim the app works unless you ran the relevant validation or clearly
158state what could not be run.
159
160### 7. Hand Off the Result
161
162End with:
163
164- what was built,
165- how to run it locally,
166- how to install or assign it in Contentful,
167- validation performed,
168- remaining assumptions, limitations, or credentials needed,
169- suggested next iteration.
170
171## Related Skills
172
173- `contentful-custom-app-enhancement` - improve or debug an existing custom app.
174- `contentful-api` - concrete CMA, CDA, CPA, Images API, and GraphQL examples.
175- `contentful-migration` - content model migration scripts.
176- `contentful-guide` - Contentful concepts and API routing.