Repo And Validation

Inspect before editing:

• package.json and lockfile to identify package manager and scripts,
• app definition, manifest, or Contentful deployment config if present,
• src/locations/, src/components/, src/hooks/, or equivalent app folders,
• tests and setup files,
• lint, typecheck, build, and preview scripts,
• existing UI library and design conventions,
• README or contributor notes for local Contentful setup.

Preserve the user’s existing stack unless there is a clear blocker.

New Project Defaults

When scaffolding from scratch:

• use npx create-contentful-app@latest <app-name>,
• prefer TypeScript,
• keep generated structure recognizable,
• add only dependencies needed by the v1 workflow,
• create a small README or setup note only if the repo lacks one and the app needs Contentful-specific local setup.

Local Development Setup

Typical local loop:

1. Install dependencies with the repo’s package manager.
2. Start the app dev server.
3. Create an app definition in a development organization.
4. Set the frontend URL to the local server.
5. Select implemented locations.
6. Install the app into a sandbox or non-production environment.
7. Assign the app to the intended content type, field, sidebar, home, or page location.
8. Exercise the main workflow with minimal test content.

Validation Matrix

Run the checks that exist in the project:

• Install: dependency install succeeds after dependency changes.
• Type safety: typecheck, tsc --noEmit, or equivalent.
• Lint/format: lint, formatter check, or equivalent.
• Tests: unit, component, or integration tests for critical app behavior.
• Build: production build or app bundle command.
• Manual smoke: Contentful web app flow with local app URL.
• Security: no secrets in code, logs, test data, screenshots, or docs.
• Runtime config: if app code reads installation parameters, search for appInstallation.getForOrganization, appInstallation.get, and getForOrganization; runtime reads should come from sdk.parameters.installation unless a CMA app-installation call is explicitly needed for remote installation records.

If a check is missing, do not invent a passing result. State the gap and run the closest meaningful alternative.

Handoff Format

Summarize:

• app name and implemented locations,
• install/config parameters,
• commands to run locally,
• app definition and assignment steps,
• validation run,
• known limitations,
• recommended next work.