storyblok-best-practices

Storyblok のベストプラクティス

Storyblok CMS 開発に関する包括的なベストプラクティスガイドです。エージェンシーの開発者を支援する AI エージェントや LLM 向けに設計されています。24 のカテゴリにわたる 40 のルールを含み、影響度に基づいて優先順位を付けることで、自動コード生成やコンテンツアーキテクチャの意思決定を支援します。

適用する場面

以下の作業では、このガイドラインを参照してください。

• Storyblok のコンテンツモデルとコンポーネントスキーマを設計する場合
• Storyblok を React、Vue、Nuxt、または Next.js と統合する場合
• Visual Editor とリアルタイムプレビューを設定する場合
• @storyblok/field-plugin を使用してカスタムフィールドプラグインを構築する場合
• Content Delivery API または Management API を実装する場合
• フィールドまたはフォルダーの翻訳を使って国際化（i18n）を設定する場合
• キャッシュ無効化と自動化のために Webhook を設定する場合
• マルチスペースアーキテクチャと CI/CD ワークフローを管理する場合
• カスタムリゾルバーを使ってリッチテキストフィールドを処理する場合
• Image Service を使って画像とパフォーマンスを最適化する場合
• ツールプラグインまたはスペースプラグイン（サイドバーアプリ）を構築する場合
• プレビュー環境と本番環境を設定する場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	コンテンツモデリング	CRITICAL	model-
2	SDK 統合	CRITICAL	sdk-
3	Visual Editor	CRITICAL	editor-
4	パフォーマンスとキャッシュ	CRITICAL	perf-
5	セキュリティと認証	CRITICAL	security-
6	フィールドプラグイン	HIGH	plugin-
7	API 開発	HIGH	api-
8	国際化	HIGH	i18n-
9	Next.js 統合	HIGH	nextjs-
10	Nuxt 統合	HIGH	nuxt-
11	アプリ開発	HIGH	app-
12	スペースとアセットの管理	HIGH	space-
13	Webhook と自動化	MEDIUM-HIGH	webhook-
14	ワークフローと公開	MEDIUM-HIGH	workflow-
15	CLI と DevOps	MEDIUM	cli-
16	テストと品質	MEDIUM	test-
17	リッチテキストとメディア	MEDIUM	richtext-
18	共通パターン	HIGH	pattern-
19	SEO と構造化データ	HIGH	seo-
20	E コマース統合	HIGH	ecommerce-
21	コンテンツ移行	MEDIUM-HIGH	migration-
22	AI 機能	MEDIUM	ai-
23	コラボレーション	MEDIUM	collaboration-
24	カスタムアプリ	MEDIUM	app-

クイックリファレンス

1. コンテンツモデリング（CRITICAL）

• model-component-structure - コンポーネントにはアトミックデザインを適用する
• model-field-configuration - バリデーションを設定してフィールドタイプを構成する
• model-block-nesting - 制約を設けてブロックのネストを管理する
• model-naming-conventions - 一貫した命名規則（snake_case）を使用する

2. SDK 統合（CRITICAL）

• sdk-storyblok-editable - コンポーネントには必ず storyblokEditable() を適用する
• sdk-component-registration - すべてのコンポーネントをグローバルに登録する
• sdk-richtext-rendering - カスタムリゾルバーを使ってリッチテキストをレンダリングする

3. Visual Editor（CRITICAL）

• editor-bridge-setup - Storyblok Bridge を正しく設定する
• editor-draft-published - 下書きと公開済みコンテンツを適切に処理する

4. パフォーマンスとキャッシュ（CRITICAL）

• perf-image-optimization - 最適化された配信には Image Service を使用する
• perf-cache-invalidation - cv パラメーターを使って適切なキャッシュ無効化を実装する
• perf-monitoring - API とコンテンツのパフォーマンスを監視する

5. セキュリティと認証（CRITICAL）

• security-token-handling - API トークンを安全に管理する
• security-roles-permissions - RBAC とアクセス制御を設定する

6. フィールドプラグイン（HIGH）

• plugin-field-development - @storyblok/field-plugin SDK を使ってフィールドプラグインを構築する

7. API 開発（HIGH）

• api-content-delivery - ページネーションを使って Content Delivery API を正しく利用する
• api-graphql - クエリを最適化するには GraphQL API を使用する
• api-management - CRUD 操作には Management API を使用する

8. 国際化（HIGH）

• i18n-field-translation - フィールド単位の翻訳を正しく実装する
• i18n-folder-level - Dimensions app を使ってフォルダー単位の翻訳を設定する

9. Next.js 統合（高）

• nextjs-app-router - Next.js App Router および RSC と統合します

10. Nuxt 統合（高）

• nuxt-integration - @storyblok/nuxt モジュールを正しく設定します

11. アプリ開発（高）

• app-tool-plugins - App Bridge を使用してツールプラグインとスペースプラグインを構築します

12. スペースとアセットの管理（高）

• space-asset-management - アセットとデータソースを整理します
• space-multi-environment - エンタープライズ向けのマルチスペースアーキテクチャ

13. Webhook と自動化（中〜高）

• webhook-configuration - コンテンツイベント用の Webhook を設定します

14. ワークフローと公開（中〜高）

• workflow-releases - Release を使用して公開をスケジュールします
• workflow-pipelines - コンテンツのステージング用にパイプラインステージを設定します

15. CLI と DevOps（中）

• cli-component-sync - CLI を使用してコンポーネントスキーマを管理します

16. テストと品質（中）

• test-preview-environments - プレビュー環境と本番環境を設定します
• test-unit-integration - 単体テスト、統合テスト、E2E テストの戦略

17. リッチテキストとメディア（中）

• richtext-media-handling - リッチテキストのメディアを正しく処理します

18. よくあるパターン（高）

• pattern-typescript - TypeScript 型を生成して使用します
• pattern-error-handling - 堅牢なエラー処理を実装します
• pattern-debugging - デバッグとトラブルシューティングのガイド
• pattern-relations-references - ストーリーリンク、リレーション、参照の解決

19. SEO と構造化データ（高）

• seo-structured-data - JSON-LD、Open Graph、サイトマップの設定

20. E コマース統合（高）

• ecommerce-integration - コマースプラットフォームの統合パターン

21. コンテンツ移行（中〜高）

• migration-patterns - コンテンツ移行の戦略とツール

22. AI 機能（中）

• ai-content-features - Storyblok の AI 機能と RAG の準備

23. コラボレーション（中）

• collaboration-realtime - リアルタイム編集、コメント、競合解決

24. カスタムアプリ（中）

• app-custom-sidebar - フィールドプラグイン以外のサイドバーアプリとツールプラグイン

基本原則

ビジュアルエディターを最優先

Storyblok のビジュアルエディターは、主要な編集環境です。

• コンポーネントには必ず storyblokEditable() を適用します
• ライブ編集用に Storyblok Bridge を設定します
• コードだけでなく、ビジュアルエディターでコンポーネントをテストします

コンテンツ配信 API と管理 API

API	用途	トークン	キャッシュ
コンテンツ配信	コンテンツの取得	パブリック／プレビュー	CDN
管理	CRUD 操作	個人用／OAuth	なし
GraphQL	読み取り専用クエリ	パブリック／プレビュー	CDN

フレームワーク統合

フレームワーク	SDK	特別な機能
React	@storyblok/react (v5+)	useStoryblokState、RSC 対応、StoryblokServerComponent
Vue	@storyblok/vue	v-editable ディレクティブ
Nuxt	@storyblok/nuxt (Nuxt 4 では v9+)	自動登録、useAsyncStoryblok、deep オプション
Next.js	@storyblok/react	ドラフトモード、ISR、App Router
Astro	@storyblok/astro	ハイブリッドレンダリング

トークンのセキュリティ

次のトークンをクライアント側のコードで公開しないでください。

• プレビュー用トークン（下書きコンテンツを表示します）
• 個人用アクセストークン（完全な書き込みアクセス権）
• OAuth トークン（スコープ付きアクセス）

クライアント側で安全に使用できます。

• パブリックトークン（公開済みコンテンツの読み取り専用）

使用方法

詳しい説明とコード例については、各ルールファイルを参照してください。

rules/model-component-structure.md
rules/sdk-storyblok-editable.md
rules/editor-bridge-setup.md
rules/perf-image-optimization.md
rules/security-token-handling.md

各ルールファイルには、次の内容が含まれています。

• 重要な理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 設定テーブルと参考資料

Key Resources

• Storyblok Documentation
• React SDK
• Nuxt Module
• Field Plugin SDK
• Storyblok CLI
• Content Delivery API
• Management API