datocms-plugin

DatoCMS プラグイン

プラグインのコードは既存ファイルにパッチを適用します。スキャフォールドの作成は、依頼された場合または存在しない場合に限ります。プロジェクトへのプラグインのインストールは CMA データであり、プラグインのコードではありません。インストール、有効化／無効化、マーケットプレイスのパッケージとプライベート URL またはバージョンの切り替え、グローバルな parameters の編集は、datocms-cma のプラグイン操作で行います。作業中のインストールに触れずにローカルテストする場合は、開発用コピーを参照してください。

ワークフロー

1. まずは内容を知らせずに確認します：
   • package.json、パッケージマネージャー、スクリプト、プラグインのメタデータ、インストール済みの SDK／UI バージョン
   • 通常は src/main.tsx または src/index.tsx にある、トップレベルの connect() 呼び出し
   • 変更対象のフックのペア、レンダリングコンポーネント、ヘルパー、CSS ファイル、現在の UI パターン
   • プラグイン内に AGENTS.md があれば、その内容
2. 依頼を分類します：
   • 既存のプラグイン： パッケージがすでに存在し、ユーザーがパッチの適用、追加、保守、修正、リリース準備、スタイル変更を依頼している場合です。これをデフォルトとします。
   • 新しいプラグイン： ユーザーがプラグインフォルダーの作成、スキャフォールド作成、ブートストラップを依頼している場合、またはプラグインプロジェクトが存在しない場合です。
   • デザイン調整： スタイル、レイアウト、情報密度、間隔、テーマ、ダークモード、Canvas トークン、レガシー CSS 変数、ハードコードされた色、フォーム、テーブル、パネル、コントロール、DatoCMS UI パターンとの統一について依頼がある場合です。
   • 複合： フックやスキャフォールドの作業とデザイン変更を一度に行います。
3. 確認しても動作に関わる選択肢が解決できない場合に限り、質問します：
   • 新しいスキャフォールドを作成する場合のプラグイン名／フォルダー名
   • パッケージのメタデータを変更する場合に、プライベートプラグインにするかマーケットプレイスプラグインにするか
   • 複数の候補がある場合の対象モデル／フィールド／画面
   • 新しい権限や依存関係の追加が許可されるかどうか
   • SDK ヘルパーではなく、ブラウザーから直接 CMA を呼び出す必要があるかどうか
4. ファイルを確認した後にリファレンスを読み込みます。変更対象の画面に対応するリファレンスを使用し、リファレンス一式を読み込まないでください。
5. 既存ファイルにパッチを適用します：
   • 既存のファイル構成、パッケージマネージャー、スクリプト、命名、UI 構造を維持します
   • 対になっているフックは一緒に更新します：宣言とレンダリング、トリガーとモーダル、ドロップダウンの宣言と実行ハンドラー
   • コードパスで必要な場合は、同じパッチ内で権限とパッケージのメタデータも更新します
   • 実装でインポートする場合に限り、依存関係を追加します
6. プラグインに既存のコマンドで検証します。ビルドスクリプトを優先し、プロジェクトにすでに定義されていて変更内容の検証に役立つ場合に限り、型チェック、リンター、テストを追加します。
7. パッチの内容、コマンドの実行結果、残りの DatoCMS 確認事項を報告します。確認事項には、設定の保存、フィールドのレンダリング、モーダルの解決、アセットの選択、権限の分岐、ページ遷移、リサイズ時の動作が含まれます。

リファレンスマップ

共通

必要な内容	読み込むファイル
継続的な保守に役立つショートカット	references/rapid-patterns.md
connect()、フックのペア、レンダリングヘルパー、Canvas、フレームサイズの詳細	references/sdk-connect-and-frames.md
ベースの ctx、エンティティリポジトリ、フォーム値、ブラウザー CMA、エンドポイント、非同期エラー	references/sdk-context-and-cma.md
対象コードに明確な前例がない場合	references/current-plugin-patterns.md
プラグイン権限の変更	references/permissions.md
ローカライズされた値、フィールドパス、Structured Text の Slate 形式のフォーム値	references/form-values.md

新しいプラグイン

必要な内容	読み込むファイル
プロジェクトファイルとパッケージのベースライン	references/project-scaffold.md
最初のフックのペアの選択	references/surface-starters.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
Structured Text のカスタマイズ	references/structured-text.md
レコード表示またはピッカークエリ	references/record-presentation.md

デザイン

必要な作業	読み込むファイル
ダークモードのみの移行	references/dark-mode-upgrade.md
最初のデザイン案	references/design-foundations.md + references/design-datocms-react-ui-bridge.md
トークン／変数の検索	references/design-tokens.md
レイアウト、ページ、分割ビュー、ツールバー	references/design-layouts.md
フォーム、コントロール、設定	references/design-forms-and-controls.md
ドロップダウン、タブ、テーブル、リスト、通知	references/design-navigation-feedback-and-data-display.md
サーフェスのシェルルール	references/design-plugin-surfaces.md
生の CSS によるフォールバックのスニペット	references/design-raw-css-fallbacks.md

デザイン作業では、必要な形状に合う場合は公開されている datocms-react-ui コンポーネントを優先してください。公開コンポーネントではレイアウトをすっきり表現できない場合に限り、ローカルの React／CSS にフォールバックしてください。Canvas のトークンと変数を直接使用し、それらで表現できない明示的な製品スタイリング、ベンダーウィジェット、メディア表現、データ可視化、エフェクトに限ってカスタマイズしてください。

ガードレール

• トップレベルの connect() 呼び出しは必ず1つだけにしてください。
• フックを追加する前に、既存の connect() を確認してください。
• プラグインのエントリーファイルで datocms-react-ui/styles.css を一度だけインポートしてください。src/vite-env.d.ts（/// <reference types="vite/client" />）を残してください。そうしないと TS がエラーを返します。
• レンダリングするすべてのサーフェスを <Canvas ctx={ctx}> で囲んでください。
• ページ、インスペクター、全幅サイドバーには <Canvas ctx={ctx} noAutoResizer> を使用してください。
• ID に応じてレンダーフックを振り分ける場合は switch を使用してください。
• SDK の型には import type { ... } を使用してください。
• 保存済みレコードのデータを読み取る前に ctx.item が存在することを確認してください。
• フィールド拡張では get(ctx.formValues, ctx.fieldPath) を使用し、それ以外ではローカライズされた値のヘルパーを使用してください。
• ctx オブジェクトのプロパティに依存する場合は、ディープ比較を行うエフェクトを使用してください。
• ctx.openModal() のパラメーターと ctx.resolve() の値は JSON シリアライズ可能な状態にしてください。
• プラグインパラメーターは、読み込み時と保存時に正規化してください。
• renderManualFieldExtensionConfigScreen では ctx.setParameters() を直接使用してください。
• Modular Content は FieldType と API の field_type では rich_text です。Modular Content、単一ブロック、Structured Text フィールド用のエディターフィールド拡張は作成しないでください。代わりにアドオンを使用してください（Modular Content の場合は fieldTypes: ['rich_text']、単一ブロックには FieldType がないため overrideFieldExtensions を使用します。すべてのフィールドタイプで提供してよい場合は fieldTypes: 'all' を使用します）。
• ブラウザーから CMA を呼び出す前に、SDK ヘルパーを優先してください。ブラウザーからの CMA 呼び出しが必要な場合は @datocms/cma-client-browser を使用し、必要な権限のみを追加し、ctx.currentUserAccessToken がない場合に備えて処理してください。
• モーダル、サイドバー、設定画面はコンパクトに保ってください。

ルーティング

• DAST の分析、検証、または変換 → datocms-structured-text：ドキュメントモデル、編集、または変換。Slate のフォーム値とエディターのフックはここで扱います。DAST を ctx.setFieldValue に渡してはいけません。DAST の作業を行う場合に限り、専門のスキルを読み込みます。参照先の兄弟ファイルが見つからない場合は、datocms/agent-skills からそのスキルをインストールするか、バンドル全体を更新してください。

• ウェブサイトのプレビュー、Content Link、ドラフトモード、キャッシュタグ、フロントエンドのレンダリング、またはフレームワークとの連携 → datocms-frontend-integrations。複数のパートからなるウェブサイト設定をガイドする場合 → datocms-setup。

• コンテンツモデリングに関する判断 → datocms-content-modeling。

• コンテンツ配信用 GraphQL クエリの作業 → datocms-cda。