contentful-custom-app-from-scratch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Contentful Custom App From Scratch

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

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.

使用此技能可将客户的应用创意转化为可本地测试的小型Contentful App Framework实现。

默认使用用户自有代码仓库、Contentful组织和应用交付工作流，除非用户明确选择其他目标环境。

公开的Contentful Marketplace应用和Contentful公开应用仓库（

https://github.com/contentful/apps

）可作为成熟App Framework模式、UX规范和配置流程的参考。可将其作为示例进行适配，而非必须遵循的仓库结构或发布流程。

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.

在编写代码前，先明确应用的用途、主要用户、受影响的内容模型以及目标Contentful界面。
仅询问会影响架构或避免错误构建的必要信息。
优先构建能在非生产空间验证价值的最小版本。
基于官方App Framework文档和当前项目结构来决定功能实现。
确保用户所有的密钥、令牌和生产内容不进入生成的代码、日志和示例中。

Workflow

工作流程

1. Create the Implementation Brief

1. 制定实现概要

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.

在搭建项目前先记录简短的概要：

一句话描述应用概念，
目标用户及其需要优化的工作流，
v1版本所需的Contentful部署位置，
涉及的内容类型、字段、语言环境和环境，
涉及的外部系统、认证或API，
预期的安装和配置模型，
v1版本必须具备的功能，
假设条件和非目标内容，
本地和沙箱测试的验证方案。

如果用户的想法仍较宽泛，可提出2-3个可行的v1版本选项，并推荐最小且实用的方案。

如需规划细节，请参考应用规划。

2. Choose the App Shape

2. 选择应用形态

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.

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

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

如果需要敏感凭证，将其建模为机密安装参数，仅在后端或基于Function的路径中使用原始值。

3. Inspect or Scaffold the Project

3. 检查或搭建项目

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.

如果用户已有代码仓库：

检查
```
package.json
```
、应用相关文档、现有应用部署位置、构建脚本、测试和样式规范。
复用仓库的框架、包管理器、代码检查/测试设置和组件模式。

确认应用是否已使用

@contentful/app-sdk

、

@contentful/react-apps-toolkit

、

@contentful/f36-components

或

contentful-management

。

如果用户没有代码仓库：

使用

npx create-contentful-app@latest <app-name>

搭建项目。

优先使用TypeScript，除非用户要求使用JavaScript。
在本地应用接入Contentful并验证前，保持初始搭建的项目与生成的结构一致。

4. Build in Contentful-Native Style

4. 采用Contentful原生风格构建

Use the App SDK or React Apps Toolkit to access the current location SDK.
Use Forma 36 components for Contentful web app UI.
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.

使用App SDK或React Apps Toolkit访问当前部署位置的SDK。
使用Forma 36组件构建Contentful Web应用的UI。
保持UI紧凑、清晰且适合编辑器使用；避免在Contentful Web应用内使用营销类布局。
当加载、空状态、权限和错误状态影响主工作流时，需包含这些状态处理。
确保字段和条目的写入操作明确、尽可能可逆且易于编辑器理解。
当运行时位置需要应用配置时，从
```
sdk.parameters.installation
```
读取安装参数。不要为了获取配置参数，在挂载副作用、渲染路径、钩子或用户交互中通过CMA获取应用安装记录。
在应用拥有多个实际使用路径前，避免使用宽泛的抽象。
不要在浏览器代码中暴露管理令牌、API密钥或第三方凭证。

5. Wire the Local App into Contentful

5. 将本地应用接入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.

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

将前端URL设置为本地开发服务器，通常为
```
http://localhost:3000
```
，
仅选择v1版本中实现的部署位置，
定义必要的安装或实例参数，
将应用安装到非生产空间或环境中，
将应用分配到相关的内容类型、字段、侧边栏、主页或页面位置，
必要时添加最小化测试内容。

如需本地测试和交接步骤，请参考仓库与验证。

6. Verify Before Handoff

6. 交接前验证

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.

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

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

除非已运行相关验证或明确说明无法运行的内容，否则不要声称应用可正常工作。

7. Hand Off the Result

7. 交付成果

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.

交付时需包含：

已构建的内容，
本地运行方法，
在Contentful中安装或分配应用的方法，
已执行的验证操作，
剩余的假设条件、限制或所需凭证，
建议的下一次迭代方向。