datocms-plugin-builder

DatoCMS Plugin Builder

デフォルトでは拡張モードを使用します。すばやく進め、調査範囲を絞り、変更は小さく保ちます。最初の状況把握を終えたら、すでに把握している箇所を再調査しないでください。

ステップ 1：作業経路を選ぶ

A. 最初に対象箇所を特定する

変更対象が明らかでない場合に使用します。

1. package.json を読み、datocms-plugin-sdk を使用していることを確認します。
2. connect() を呼び出しているエントリーポイント（src/main.tsx、src/index.tsx）を探します。
3. フックを変更する前に、既存の connect() 呼び出しを確認します。
4. 依頼内容から、変更対象を最小限に絞ります。
   • 設定画面／プラグインパラメーター
   • フィールド拡張または手動のフィールド拡張設定
   • サイドバーパネル、フルサイドバー、アウトレット、カスタムページ
   • ドロップダウンアクションまたはライフサイクルフック
   • モーダル、インスペクター、アセットソース、アップロードサイドバー
   • レコード表示または構造化テキストのカスタマイズ
   • プラグイン周辺の依存関係、ビルド、型の修正
5. 変更に直接関係する経路だけを読みます。
   • connect() のエントリーファイル
   • 編集するコンポーネントまたはヘルパー
   • あわせて変更する必要があるインポート先のファイル
6. 現在のファイル構成、命名、UI パターンを再利用します。

B. すばやい追加修正

以前の文脈やリポジトリの直接確認から対象箇所が明らかな場合に使用します。

1. 変更対象のレンダリング分岐、コンポーネント、ヘルパーだけを再度開きます。
2. フックの組み合わせ、パラメーターの形状、必要な権限が引き続き適切か確認します。
3. 既存の分岐、コンポーネント、ヘルパーを直接修正します。
4. コードから答えが得られなくならない限り、広範な再調査は省略します。

明らかな小規模修正で、最初からすべてを再調査しないでください。

ステップ 2：リポジトリから答えが得られない場合のみ質問する

原則として質問はしません。

誤った想定によって動作が大きく変わり、リポジトリから答えを得られない場合に限り、質問してください。

• 使用する DatoCMS の対象機能
• 対象とするモデルまたはフィールドの範囲
• 新しい権限または外部依存関係を許可するか
• フローを SDK ヘルパー内に維持する必要があるか、ブラウザーから CMA を呼び出す必要があるか

プラグインプロジェクトが存在しない場合、またはユーザーが新しいプラグインフォルダーの作成を希望する場合は、datocms-plugin-scaffold に切り替えます。

ステップ 3：必要なリファレンスだけを読み込む

まずプロジェクトのコードを確認します。

2日目／3日目の保守パターンについては、最初に references/rapid-patterns.md を読み込みます。その後、必要な対象機能のリファレンスだけを読み込みます。

対象機能のリファレンス

• 設定画面／プラグインパラメーター → references/config-screen.md
• フィールド拡張／フィールドごとの設定 → references/field-extensions.md
• サイドバーパネル／フルサイドバー → references/sidebar-panels.md
• カスタムページ → references/custom-pages.md
• ドロップダウンアクション → references/dropdown-actions.md
• ライフサイクルフック → references/lifecycle-hooks.md
• モーダル → references/modals.md
• アウトレット → references/outlets.md
• インスペクター → references/inspectors.md
• アセットソース → references/asset-sources.md
• アップロードサイドバー／パネル → references/upload-sidebars.md
• 構造化テキストのカスタマイズ → references/structured-text.md
• レコード表示 → references/record-presentation.md

条件に応じて読み込む

• フックの接続や調整、レンダリングの切り替え、モーダルのフロー、フレームのサイズ動作を扱う場合は references/connect-conventions.md
• フィールド拡張以外で ctx.formValues を読み取る場合、または構造化テキスト／モジュラーコンテンツの値を扱う場合に限り、references/form-values.md
• プラグイン権限の追加または削除、ctx.currentUserAccessToken の使用、権限によって表示が切り替わる UI 分岐のリリースを行う場合は references/permissions.md
• より限定的なリファレンスでは SDK やブラウザー CMA に関する詳しい疑問に答えられない場合に限り、references/sdk-architecture.md

小さなパッチでリファレンス一式を読み込まないでください。

ステップ 4：最小限のパッチを作成する

プラグインを再構成するより、既存の宣言、レンダーの switch、コンポーネント、またはヘルパーを編集してください。

• ファイルの移動は、全体の複雑さを軽減するか、繰り返しの表層的な接着コードをなくせる場合に限ります。
• 新しいファイルの追加は、パッチが小さくなる場合、または変更対象のフローで共有する正規化処理やブラウザー CMA の処理を切り分けられる場合に限ります。
• 依存関係の変更は最小限にし、コードが実際に使用するパッケージのみを追加してください。
• ユーザーが再設計を依頼していない限り、既存の UI スタイルを維持してください。

次のガードレールを守ってください。

• フックを追加する前に、既存の connect() 呼び出しを確認してください。
• トップレベルの connect() 呼び出しは必ず 1 つだけにしてください。
• フローに必要な場合は、宣言、レンダー、実行、パッケージ権限をまとめて更新してください。
• レンダリングする UI は <Canvas ctx={ctx}> で囲んでください。noAutoResizer を使用するのは、ページ、インスペクター、全幅サイドバーに限ります。
• ID によってディスパッチされるレンダーフックには switch を使用してください。
• SDK の型には import type { ... } を使用してください。
• レコードデータを読み取る前に ctx.item をガードしてください。
• フィールド拡張では get(ctx.formValues, ctx.fieldPath) を使用し、それ以外では references/form-values.md のローカライズ値のパターンを使用してください。
• ctx オブジェクトのプロパティに依存する場合は、useEffect の代わりに useDeepCompareEffect を使用してください。
• ctx.openModal() のパラメーターと ctx.resolve() の値は、JSON にシリアライズ可能なものにしてください。
• 画面全体を書き換えるのではなく、読み込み時または保存時の境界で、保存済みのプラグインパラメーターを正規化してください。
• renderManualFieldExtensionConfigScreen では ctx.setParameters() を直接使用してください。
• モジュラーコンテンツ、単一ブロック、構造化テキストの各フィールドにはエディターフィールド拡張を作成せず、アドオン拡張を使用してください。
• 標準的なコントロール、余白、レイアウトには datocms-react-ui と小さなローカルコンポーネントを優先してください。
• 標準コンポーネントでは適切に表現できないツールのような操作に限り、より重いカスタム UI を導入してください。
• プラグインの画面とモーダルはコンパクトに保ち、ダッシュボード風のレイアウト、入れ子のパネル、装飾的なセクション、過剰な設計は避けてください。
• SDK ヘルパーでは不十分な場合に限り、ブラウザー CMA のフローを使用してください。権限の変更と実行時ガードは連動させてください。

メンテナンスの簡略化

• 設定画面の編集：パラメーターは一度だけ正規化し、保存ロジックは限定的に保ち、フォームを導入する十分な理由がない限り、通常のローカル状態を使用してください。
• アセットソースとモーダル：主な経路として assetSources／renderAssetSource を維持し、モーダルは対象を絞ったサブステップにのみ使用し、最後に ctx.select() を呼び出してください。
• アップロードサイドバーとモーダル：サイドバーは情報表示または単一アクションに限定し、対象を絞った編集にはモーダルを開き、最小限のペイロードを返して解決してください。
• 高さ／リサイズ：まず <Canvas ctx={ctx}> に任せてください。初回描画には initialHeight を指定し、非同期処理やカスタムレイアウトの変更で必要な場合に限り、ResizeObserver と ctx.updateHeight() を使用してください。
• プラグイン UI からのブラウザー CMA：まず SDK ヘルパーを優先してください。プラグインがアップロードやレコードを直接作成する必要がある場合は、ctx.currentUserAccessToken とともに @datocms/cma-client-browser を使用してください。
• 権限の追加：コードパスで実際に使用する権限のみを追加し、その後、package.json、実行時ガード、ユーザーに表示される操作を整合させてください。

ステップ 5：必要最小限の有用なチェックで検証する

変更を適切に確認できる既存の検証手段のうち、最も軽量なものを実行してください。

• コード変更では、デフォルトでリポジトリの既存ビルドスクリプト（npm run build、pnpm build など）
• プロジェクトに適切なテストまたは型チェックのコマンドがある場合は、そのうち最も関連性の高いもの
• 依存関係を変更した場合は、検証の前にリポジトリのパッケージマネージャーで依存関係をインストール

適切なスクリプトがリポジトリにない場合は、既存のビルド、型チェック、または lint コマンドのうち、最も近いものを実行してください。

次の内容を報告してください。

1. 変更した内容
2. 実行した内容
3. 依然として必要な、DatoCMS での手動チェック 1 件

この手動チェックは、変更した箇所に合わせてください。たとえば、設定の保存経路、モーダルの解決経路、アセット／アップロードの選択フロー、権限で制御される分岐、または非同期コンテンツの読み込み後のリサイズ動作が該当します。

スキル間の振り分け

• プラグインをゼロから新規作成する場合 -> datocms-plugin-scaffold
• ネイティブな DatoCMS プラグイン UI のデザイン、レイアウトのスタイル変更、またはデザインシステムとの整合 -> datocms-plugin-design-system
• iframe 内でプラグインに埋め込まれたブラウザーから CMA を使用する場合 -> このスキルを使用します
• プラグインの iframe 外でスタンドアロンの CMA スクリプトを使用する場合、またはスキーマを扱う場合 -> datocms-cma
• プラグイン外でフロントエンドのプレビュー、Content Link、またはキャッシュタグを扱う場合 -> datocms-frontend-integrations