contentful-custom-app-from-scratch

从零开始创建 Contentful 自定义应用

使用此技能，将客户的应用构想转化为一个可在本地测试的小型 Contentful App Framework 实现。

除非用户明确选择其他目标位置，否则默认使用用户自己的代码仓库、Contentful 组织和应用交付工作流。

公开的 Contentful Marketplace 应用和 Contentful 的公开应用代码仓库 （https://github.com/contentful/apps）可作为成熟 App Framework 模式、UX 惯例和配置流程的参考。将它们作为可借鉴的示例，而不是必须遵循的仓库结构或发布流程。

工作方式

• 编写代码前，先明确应用的用途、主要用户、受影响的内容模型和目标 Contentful 界面。
• 只询问会影响架构或可能导致错误实现的信息。
• 优先构建能在非生产环境中验证价值的最小版本。
• 根据官方 App Framework 文档和当前项目结构，确定功能方案。
• 不要将用户拥有的密钥、令牌和生产内容放入生成的代码、日志和示例中。

工作流

1. 制定实施概要

在搭建项目之前，先记录一份简短概要：

• 一句话描述应用构想，
• 目标用户及需要改进的工作流，
• v1 需要使用的 Contentful 位置，
• 涉及的内容类型、字段、本地化设置和环境，
• 涉及的外部系统、身份验证或 API，
• 预期的安装和配置模式，
• v1 必须实现的行为，
• 假设和非目标，
• 本地和沙盒测试的验证计划。

如果构想仍然宽泛，提出 2-3 个可行的 v1 方案，并推荐最小且实用的方案。

规划详情请参阅 应用规划。

2. 选择应用形式

根据用户工作流选择位置：

• 如果应用需要在安装时进行设置，请使用 app-config。
• 对于条目级上下文、状态、辅助操作和轻量级洞察，请使用 entry-sidebar。
• 如需替换或增强字段的编辑体验，请使用 entry-field。
• 对于从其他位置启动的专用选择器、确认或多步流程，请使用 dialog。
• 对于仪表板、批量工具、引导流程或全屏操作工作流，请使用 page 或 home。
• 只有在替换或大幅扩展完整条目编辑体验的收益值得承担维护成本时，才使用 entry-editor。
• 只有在应用需要异步行为、服务器端执行、经过验证的入站请求、事件处理，或在浏览器之外访问机密值时，才使用 App Actions 或 Functions。

如果需要敏感凭据，应将其建模为机密安装参数，并且仅在由后端或 Function 支持的路径中使用原始值。

3. 检查或搭建项目

如果用户已有代码仓库：

1. 检查 package.json、应用相关文档、现有应用位置、构建脚本、测试和样式规范。
2. 复用代码仓库的框架、包管理器、lint/test 配置和组件模式。
3. 确认应用是否已使用 @contentful/app-sdk、 @contentful/react-apps-toolkit、@contentful/f36-components 或 contentful-management。

如果用户没有代码仓库：

1. 使用 npx create-contentful-app@latest <app-name> 搭建项目。
2. 除非用户要求使用 JavaScript，否则优先使用 TypeScript。
3. 在本地应用接入 Contentful 并完成验证之前，让首个脚手架项目尽量保持生成时的结构。

4. 采用 Contentful 原生风格构建

• 使用 App SDK 或 React Apps Toolkit 访问当前所在位置的 SDK。
• 使用 Forma 36 组件构建 Contentful Web 应用的 UI。尝试自定义构建前，务必先检查 Forma 36 是否提供类似组件。
• 保持 UI 紧凑、清晰且便于编辑；避免在 Contentful Web 应用中使用营销页面布局。
• 在会影响主要工作流时，提供加载、空内容、权限和错误状态。
• 明确执行字段和条目写入；尽可能确保可撤销，并让编辑者易于理解。
• 当运行时位置需要应用配置时，从 sdk.parameters.installation 读取安装参数。不要在挂载副作用、渲染路径、钩子或用户交互中通过 CMA 获取应用安装记录，只为读取已配置的参数。
• 在应用尚未有多个实际使用场景之前，避免创建宽泛的抽象。
• 不要在浏览器代码中暴露管理令牌、API 密钥或第三方凭据。

5. 将本地应用接入 Contentful

在开发组织或沙盒中创建或更新应用定义：

• 将前端 URL 设置为本地开发服务器，通常为 http://localhost:3000，
• 仅选择 v1 中已实现的位置，
• 定义必需的安装参数或实例参数，
• 将应用安装到非生产空间或环境中，
• 将应用分配到相关内容类型、字段、侧边栏、主页或页面位置，
• 按需填充最少量的测试内容。

有关本地测试和交接步骤，请参阅 仓库与验证。

6. 交接前进行验证

在用户的项目中运行最相关的可用检查：

• 依赖项发生变化时，检查包安装，
• 类型检查和 lint，
• 单元测试或组件测试，
• 生产构建，
• 本地开发服务器冒烟测试，
• 在非生产空间中手动测试 Contentful Web 应用流程。
• 当运行时代码读取安装参数时，对应用源代码运行 rg -n "appInstallation\\.(getForOrganization|get)\\(|getForOrganization"， 并说明任何剩余的 CMA 应用安装调用。

除非运行了相关验证，否则不要声称应用可用；如果有验证无法运行，请明确说明。

7. 交接结果

最后说明：

• 构建了什么，
• 如何在本地运行，
• 如何在 Contentful 中安装或分配，
• 已执行的验证，
• 尚存的假设、限制或所需凭据，
• 建议的下一轮迭代。

相关技能

• contentful-custom-app-enhancement — 改进或调试现有自定义应用。
• contentful-api — 具体的 CMA、CDA、CPA、Images API 和 GraphQL 示例。
• contentful-migration — 内容模型迁移脚本。
• contentful-guide — Contentful 概念和 API 路由。