cloudinary-next

Cloudinary Next

目的

このスキルは、next-cloudinary と、サーバー専用の操作には Cloudinary Node SDK v2 を使用して Cloudinary を統合する Next.js プロジェクトの構築、デバッグ、レビューを開発者が行う際に役立ちます。

このスキルは、段階的に読み込めるように構成されています。既定では、すべてのリファレンスファイルを読み込まないでください。以下のワークフローから始め、ユーザーのタスクに必要なリファレンスファイルだけを読み込んでください。

基本的なワークフロー

1. コードを書く前に、ユーザーの目的を分類します。
   • JSX で変換済みの Cloudinary 画像をレンダリングする
   • Cloudinary URL 文字列を生成する
   • 動画プレーヤーを埋め込む
   • ブラウザーからアップロードする
   • 署名付きアップロードを実行する
   • サーバーからアップロードする
   • アセットを削除する
   • オーバーレイまたはテキストオーバーレイを作成する
   • OG／ソーシャル画像を生成する
   • TypeScript、環境設定、インポート、ランタイム、アップロードのエラーを修正する
   • 既存の実装をレビューする
2. 以下のマップから関連するリファレンスファイルを読み込みます。
3. 詳細なリファレンスを使用する前に、この SKILL.md の必須ルールを適用します。
4. コードレビューやデバッグでは、references/troubleshooting.md とタスク固有のリファレンスを読み込みます。
5. 詳細がバージョンに依存する場合、またはここに記載されていない場合は、references/official-docs.md にリンクされている公式ドキュメントを参照し、記憶に頼るのではなく公式のプロパティ名とイベント名を優先します。

必須ルール

• Next.js のコンポーネントと URL ヘルパーには next-cloudinary を使用します。対象は CldImage、CldVideoPlayer、CldUploadWidget、CldUploadButton、CldOgImage、getCldImageUrl、getCldOgImageUrl、getCldVideoUrl です。
• Cloudinary Node SDK v2 は、サーバー側の操作にのみ使用します。import { v2 as cloudinary } from 'cloudinary' を使用してください。
• CLOUDINARY_API_SECRET をブラウザーに公開しないでください。NEXT_PUBLIC_CLOUDINARY_API_SECRET は作成しないでください。
• アップロードウィジェット、動画プレーヤーの UI、React のイベントハンドラーを持つコンポーネントは、'use client' を付けた Client Component の境界内に配置してください。
• CldImage は静的レンダリングのために Server Component から使用できます。ただし、onLoad やローカル状態など、クライアント専用のプロパティを追加する場合は、Client Component に移してください。
• Client Component や Edge ランタイムコードから cloudinary をインポートしないでください。cloudinary をインポートする Server Action とルートハンドラーは、Node.js ランタイムで実行する必要があります。
• ドキュメントに記載された next-cloudinary のプロパティ名と形式を使用してください。Cloudinary URL の変換パラメーターからプロパティ名を推測しないでください。
• アップロードウィジェットの成功処理には onSuccess を使用してください。インストール済みのバージョンで明示的に記載されていない限り、非推奨のアップロードコールバック名は使用しないでください。
• 削除時には、配信 URL ではなく public ID を渡してください。動画または raw アセットを削除するときは resource_type を渡し、CDN キャッシュの無効化が必要な場合は invalidate: true を使用してください。

リファレンスマップ

役立つ最小限のリファレンスを読み込みます。

• references/official-docs.md — 公式ドキュメントへのリンクと、全体に適用されるプロパティ名のルールです。
• references/api-decision-tree.md — ユーザーの目的に応じて、適切な Cloudinary API／コンポーネント／ヘルパーを選択します。
• references/project-setup.md — パッケージのインストール、Next.js の画像ドメインの設定、アップロードプリセットの設定、初期設定ファイルの作成を行います。
• references/environment.md — 環境変数と TypeScript の process env 型付けについて説明します。
• references/imports.md — 正しいインポートパスとサーバー／クライアントの境界について説明します。
• references/cldimage.md — CldImage、サンプルアセット、getCldImageUrl の使い方について説明します。
• references/cldimage-transformations.md — 変換用プロパティ、生成編集、最適化、Raw 変換、クロップ時の注意点について説明します。
• references/responsive-images.md — レスポンシブ画像のサイズ設定と sizes の指針について説明します。
• references/video-player.md — CldVideoPlayer、必須の CSS、クライアント専用プレーヤーの設定について説明します。
• references/upload-widget.md — ブラウザーからのアップロード、アップロードウィジェット／ボタンの使い方、イベント、署名付きアップロードと署名なしアップロードのトレードオフについて説明します。
• references/signed-uploads.md — App Router の署名エンドポイントのパターンについて説明します。
• references/server-upload-delete.md — Node SDK v2 を使った Server Action と route handler によるアップロード／削除のパターンについて説明します。
• references/overlays.md — 画像オーバーレイとテキストオーバーレイのプロパティ形式について説明します。
• references/og-images.md — App Router と Pages Router での OG／ソーシャルカードのパターンについて説明します。
• references/typescript.md — アップロード結果の型の絞り込み、サーバーアップロード結果の型、ref、any の回避について説明します。
• references/troubleshooting.md — よくあるエラーメッセージとその修正方法について説明します。
• references/quick-checklist.md — 最終的なコードレビューのチェックリストとベストプラクティスについて説明します。

出力に関する要件

コードを生成する場合は、ファイルパス、関連するコード全体のコードブロック、コードの実行場所（Client Component、Server Component、Server Action、route handler）についての短い説明を含めてください。

コードをレビューする場合は、次の順序で問題を報告してください。シークレットの露出、サーバー／クライアント境界の誤り、インポート／実行時の誤り、コンポーネント／ヘルパーの選択ミス、プロパティ名／イベント名の誤り、TypeScript の型の絞り込み不足、キャッシュ無効化またはリソース型の処理漏れ。

再利用可能なテンプレートを使う場合は、assets/app-router-signature-route.ts、assets/server-action-upload.ts、または assets/server-action-delete.ts からコピーし、ユーザーのプロジェクトに合わせて名前、フォルダー、戻り値を調整してください。