contentful-custom-app-from-scratch

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:

1. Inspect package.json, app-related docs, existing app locations, build scripts, tests, and style conventions.
2. Reuse the repo's framework, package manager, lint/test setup, and component patterns.
3. 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:

1. Scaffold with npx create-contentful-app@latest <app-name>.
2. Prefer TypeScript unless the user requests JavaScript.
3. 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.