sanity-best-practices

Sanity のベストプラクティス

Sanity が管理する、Sanity 開発に関する包括的なベストプラクティスと統合ガイドです。以下のクイックリファレンスを使って、タスクに合ったトピックファイルを 1 つか 2 つだけ読み込んでください。

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• 新しい Sanity プロジェクトをセットアップするとき、またはオンボーディングを行うとき
• Sanity をフロントエンドフレームワーク（Next.js、Nuxt、Astro、Remix、SvelteKit、Hydrogen）と統合するとき
• GROQ クエリを記述するとき、またはパフォーマンスを最適化するとき
• コンテンツスキーマを設計するとき
• ビジュアル編集とライブプレビューを実装するとき
• 画像、Portable Text、またはページビルダーを扱うとき
• Sanity Studio の構成を設定するとき
• 型安全性のために TypeGen をセットアップするとき
• ローカライズを実装するとき
• 他のシステムからコンテンツを移行するとき
• Sanity App SDK を使ってカスタムアプリを構築するとき
• Sanity Dashboard で Studio またはアプリを開発、デプロイするとき
• Blueprints でインフラストラクチャを管理するとき
• Sanity Functions または Webhook を使ってコンテンツのワークフローを自動化するとき

全般的なルール

• 通常のドキュメントでは Sanity に _id の値を生成させてください。ドキュメントの作成時に、決定論的な UUID、スラッグから派生した ID、またはレガシーシステムの ID を作成しないでください。
• reference フィールドでリレーションシップをモデル化し、GROQ のルックアップ、ソースキーのフィールド、または作成したドキュメントから返された _id の値を使って関連ドキュメントを解決してください。
• 明示的なドキュメント ID は、主に Studio Structure で管理されるシングルトンドキュメントに使用してください。homePage-en のようなローカライズされたシングルトンも含まれます。

動画

• 本番環境での再生向けに、Sanity の file アセットに動画を保存したり、そこから配信したりしないでください。ファイルアセットはトランスコードやアダプティブストリーミングなしで生のダウンロードとして配信されるため、動画のトラフィックは非常に大きな帯域幅を消費し、予想外に高額な請求につながります。
• 動画アドオン付きの Enterprise プランでは、動画に Sanity Media Library を使用してください。アップロードされた動画はトランスコードされ、Mux 経由でアダプティブストリーミングされます。sanity/media-library の defineVideoField() で動画フィールドをモデル化し、アセットの再生 ID を使って @mux/mux-player-react で再生してください。
• その他のプランでは、専用の動画サービスを使用してください。sanity-plugin-mux-input をインストールして Studio から Mux アカウント内の動画をアップロード、管理するか、YouTube や Vimeo などのプラットフォームで動画をホストし、埋め込み URL のみを Sanity に保存してください。
• file フィールドでは、小さなクリップや短いプレビューは問題ありませんが、多数のユーザー向け動画はすべて Media Library またはストリーミングサービス経由で配信する必要があります。

クイックリファレンス

統合ガイド

• get-started - 新しい Sanity プロジェクト向けのインタラクティブなオンボーディング
• nextjs - Next.js App Router、Live Content API、スタンドアロン Studio
• nuxt - @nuxtjs/sanity との Nuxt 統合
• angular - @sanity/client、シグナル、リソース API との Angular 統合
• astro - @sanity/astro との Astro 統合
• remix - React Router / Remix の統合
• svelte - @sanity/svelte-loader との SvelteKit 統合
• hydrogen - Sanity を使った Shopify Hydrogen
• project-structure - スタンドアロン Studio とモノレポのパターン
• app-sdk - Sanity App SDK を使ったカスタムアプリ
• dashboard - Sanity Dashboard の Studio とアプリ：defineApplication、ローカル開発、デプロイ、Dashboard フック
• blueprints - Infrastructure as Code：ブループリントファイル、スタック、計画／デプロイのワークフロー、エラー復旧、CI デプロイ
• functions - Sanity Functions と Webhook を使ったコンテンツのワークフローの自動化

トピックガイド

• groq - GROQ クエリパターン、型安全性、パフォーマンスの最適化
• schema - スキーマ設計、フィールド定義、バリデーション、非推奨化のパターン
• visual-editing - プレゼンテーションツール、Stega、オーバーレイ、ライブプレビュー
• page-builder - Page Builder の配列、ブロックコンポーネント、ライブ編集
• portable-text - リッチテキストのレンダリングとカスタムコンポーネント
• image - 画像スキーマ、URL ビルダー、ホットスポット、LQIP、Next.js Image
• studio-structure - デスク構造、シングルトン、ナビゲーション
• typegen - TypeGen の設定、ワークフロー、型ユーティリティ
• seo - メタデータ、サイトマップ、Open Graph、JSON-LD
• localization - i18n パターン、ドキュメント単位とフィールド単位、ロケール管理
• migration - コンテンツインポートの概要（migration-html-import も参照）
• migration-html-import - @portabletext/block-tools を使った HTML から Portable Text への変換

使い方

まず、依頼に最も合った単一のフレームワークガイドまたはトピックガイドを確認し、タスクが複数の領域にまたがる場合にのみ追加のリファレンスを読みます。詳細な説明とコード例については、以下のリファレンスファイルを使用してください。

references/groq.md
references/schema.md
references/nextjs.md

各リファレンスファイルには、以下が含まれています。

• トピックまたは統合に関する包括的な情報
• 誤ったコード例と正しいコード例
• 判断マトリックスとワークフローのガイダンス
• 該当する場合は、フレームワーク固有のパターン