contentful-custom-app-from-scratch

Contentful Custom App From Scratch

このスキルを使うと、顧客のアプリのアイデアを、ローカルでテスト可能な小規模な Contentful App Framework の実装に変換できます。

ユーザーが別の配信先を明示的に選ばない限り、ユーザー自身のリポジトリ、Contentful 組織、アプリの配信ワークフローをデフォルトで使用してください。

公開されている Contentful Marketplace のアプリや、Contentful の公開アプリリポジトリ （https://github.com/contentful/apps）は、成熟した App Framework のパターン、UX の慣例、設定フローを把握するうえで役立つ参考資料です。必須のリポジトリ構成や公開プロセスとしてではなく、応用できる例として活用してください。

作業スタイル

• コードを書く前に、アプリの役割、主なユーザー、影響を受けるコンテンツモデル、対象となる Contentful の画面を明確にしてください。
• アーキテクチャに影響する、または誤った実装を防ぐために必要な情報だけを質問してください。
• 本番環境以外のスペースで価値を実証できる、最小限のバージョンを優先してください。
• 機能を判断する際は、公式の App Framework ドキュメントと現在のプロジェクト構成を根拠にしてください。
• ユーザーが所有するシークレット、トークン、本番コンテンツを、生成コード、ログ、サンプルに含めないでください。

ワークフロー

1. 実装概要を作成する

スキャフォールディングの前に、以下の項目を簡潔にまとめてください。

• 1 文で表したアプリのコンセプト
• 対象ユーザーと、改善が必要なワークフロー
• v1 で必要な Contentful のロケーション
• 関連するコンテンツタイプ、フィールド、ロケール、環境
• 関連する外部システム、認証、API
• 想定するインストールと設定のモデル
• v1 で必須の動作
• 前提条件と対象外の項目
• ローカルテストとサンドボックステストの検証計画

アイデアの範囲がまだ広い場合は、実現可能な v1 の選択肢を 2～3 個提案し、最小限で役に立つものを推奨してください。

計画の詳細については、アプリの計画を参照してください。

2. アプリの形を選ぶ

ユーザーのワークフローに応じてロケーションを選んでください。

• インストール時のセットアップが必要な場合は、app-config を使用してください。
• エントリーレベルのコンテキスト、ステータス、補助アクション、簡易なインサイトには、entry-sidebar を使用してください。
• フィールドの編集エクスペリエンスを置き換える、または強化する場合は、entry-field を使用してください。
• 別のロケーションから起動する、専用のピッカー、確認、複数ステップのフローには、dialog を使用してください。
• ダッシュボード、一括操作ツール、オンボーディング、全画面の運用ワークフローには、page または home を使用してください。
• エントリー編集エクスペリエンス全体を置き換える、または大幅に拡張する価値が保守コストを上回る場合に限り、entry-editor を使用してください。
• 非同期処理、サーバーサイド実行、検証済みの受信リクエスト、イベント処理、またはブラウザー外でのシークレット値へのアクセスが必要な場合に限り、App Actions または Functions を使用してください。

機密性の高い認証情報が必要な場合は、インストール時のシークレットパラメーターとしてモデル化し、生の値はバックエンドまたは Function を使用する経路でのみ利用してください。

3. プロジェクトを調査するか、スキャフォールディングする

ユーザーがすでにリポジトリを持っている場合：

1. package.json、アプリ関連のドキュメント、既存のアプリロケーション、ビルドスクリプト、テスト、スタイルの規約を調査してください。
2. リポジトリのフレームワーク、パッケージマネージャー、lint／テストの設定、コンポーネントのパターンを再利用してください。
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 にアクセスします。
• Contentful のウェブアプリ UI には Forma 36 コンポーネントを使用します。カスタムコンポーネントの構築を試みる前に、Forma 36 に同様のコンポーネントがないか必ず確認してください。
• UI は情報密度が高く、明快で、編集者が使いやすいものにします。Contentful のウェブアプリ内でマーケティング向けのレイアウトは避けてください。
• メインのワークフローに影響する場合は、読み込み中、空の状態、権限、エラーの各状態を含めます。
• フィールドとエントリーへの書き込みは明示的に行い、可能な限り元に戻せるようにして、編集者が理解しやすいものにします。
• 実行時のロケーションでアプリの設定が必要な場合は、sdk.parameters.installation からインストールパラメーターを読み取ります。設定済みのパラメーターを取得するためだけに、マウント時のエフェクト、レンダリングパス、フック、ユーザー操作から CMA 経由でアプリのインストールレコードを取得しないでください。
• アプリに実際の使用経路が複数できるまでは、広範な抽象化を避けます。
• 管理トークン、API キー、サードパーティの認証情報をブラウザーコードで公開しないでください。

5. ローカルアプリを Contentful に接続する

開発用の組織またはサンドボックスで、アプリ定義を作成または更新します。

• フロントエンド URL をローカル開発サーバーに設定します。通常は http://localhost:3000 です。
• v1 で実装したロケーションのみを選択します。
• 必須のインストールパラメーターまたはインスタンスパラメーターを定義します。
• アプリを本番環境以外のスペースまたは環境にインストールします。
• アプリを関連するコンテンツタイプ、フィールド、サイドバー、ホームページ、またはページロケーションに割り当てます。
• 必要に応じて、最小限のテストコンテンツを用意します。

ローカルテストと引き継ぎの手順については、 リポジトリと検証を参照してください。

6. 引き継ぎの前に検証する

ユーザーのプロジェクトで実行できる、最も適切なチェックを行います。

• 依存関係を変更した場合は、パッケージのインストールチェック
• 型チェックと lint
• 単体テストまたはコンポーネントテスト
• 本番ビルド
• ローカル開発サーバーのスモークテスト
• 本番環境以外のスペースで、Contentful ウェブアプリのフローを手動で確認
• 実行時コードでインストールパラメーターを読み取る場合は、アプリのソース全体に対して 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 のルーティングです。