Storyblok Best Practices
Comprehensive best practices guide for Storyblok CMS development, designed for AI agents and LLMs helping agency developers. Contains 40 rules across 24 categories, prioritized by impact to guide automated code generation and content architecture decisions.
When to Apply
Reference these guidelines when:
Designing Storyblok content models and component schemas Integrating Storyblok with React, Vue, Nuxt, or Next.js Configuring Visual Editor and real-time preview Building custom field plugins with @storyblok/field-plugin Implementing Content Delivery API or Management API Setting up internationalization (i18n) with field or folder translations Configuring webhooks for cache invalidation and automation Managing multi-space architectures and CI/CD workflows Handling rich text fields with custom resolvers Optimizing images and performance with Image Service Building tool plugins or space plugins (sidebar apps) Setting up preview/production environments Rule Categories by Priority Priority Category Impact Prefix 1 Content Modeling CRITICAL model- 2 SDK Integration CRITICAL sdk- 3 Visual Editor CRITICAL editor- 4 Performance & Caching CRITICAL perf- 5 Security & Authentication CRITICAL security- 6 Field Plugins HIGH plugin- 7 API Development HIGH api- 8 Internationalization HIGH i18n- 9 Next.js Integration HIGH nextjs- 10 Nuxt Integration HIGH nuxt- 11 App Development HIGH app- 12 Space & Asset Management HIGH space- 13 Webhooks & Automation MEDIUM-HIGH webhook- 14 Workflows & Publishing MEDIUM-HIGH workflow- 15 CLI & DevOps MEDIUM cli- 16 Testing & Quality MEDIUM test- 17 Rich Text & Media MEDIUM richtext- 18 Common Patterns HIGH pattern- 19 SEO & Structured Data HIGH seo- 20 E-commerce Integration HIGH ecommerce- 21 Content Migration MEDIUM-HIGH migration- 22 AI Features MEDIUM ai- 23 Collaboration MEDIUM collaboration- 24 Custom Apps MEDIUM app- Quick Reference 1. Content Modeling (CRITICAL) model-component-structure - Follow atomic design for components model-field-configuration - Configure field types with validation model-block-nesting - Manage block nesting with restrictions model-naming-conventions - Use consistent naming (snake_case) 2. SDK Integration (CRITICAL) sdk-storyblok-editable - Always apply storyblokEditable() to components sdk-component-registration - Register all components globally sdk-richtext-rendering - Render rich text with custom resolvers 3. Visual Editor (CRITICAL) editor-bridge-setup - Configure Storyblok Bridge correctly editor-draft-published - Handle draft/published content properly 4. Performance & Caching (CRITICAL) perf-image-optimization - Use Image Service for optimized delivery perf-cache-invalidation - Implement proper cache invalidation with cv parameter perf-monitoring - API and content performance monitoring 5. Security & Authentication (CRITICAL) security-token-handling - Secure API token management security-roles-permissions - RBAC and access control configuration 6. Field Plugins (HIGH) plugin-field-development - Build field plugins with @storyblok/field-plugin SDK 7. API Development (HIGH) api-content-delivery - Use Content Delivery API correctly with pagination api-graphql - Use GraphQL API for optimized queries api-management - Use Management API for CRUD operations 8. Internationalization (HIGH) i18n-field-translation - Implement field-level translations correctly i18n-folder-level - Folder-level translations with Dimensions app 9. Next.js Integration (HIGH) nextjs-app-router - Integrate with Next.js App Router and RSC 10. Nuxt Integration (HIGH) nuxt-integration - Configure @storyblok/nuxt module correctly 11. App Development (HIGH) app-tool-plugins - Build tool and space plugins with App Bridge 12. Space & Asset Management (HIGH) space-asset-management - Organize assets and datasources space-multi-environment - Multi-space architecture for enterprise 13. Webhooks & Automation (MEDIUM-HIGH) webhook-configuration - Configure webhooks for content events 14. Workflows & Publishing (MEDIUM-HIGH) workflow-releases - Use Releases for scheduled publishing workflow-pipelines - Pipeline stages for content staging 15. CLI & DevOps (MEDIUM) cli-component-sync - Use CLI for component schema management 16. Testing & Quality (MEDIUM) test-preview-environments - Set up preview and production environments test-unit-integration - Unit, integration, and E2E testing strategies 17. Rich Text & Media (MEDIUM) richtext-media-handling - Handle rich text media correctly 18. Common Patterns (HIGH) pattern-typescript - Generate and use TypeScript types pattern-error-handling - Implement robust error handling pattern-debugging - Debugging and troubleshooting guide pattern-relations-references - Story links, relations, and reference resolution 19. SEO & Structured Data (HIGH) seo-structured-data - JSON-LD, Open Graph, and sitemap configuration 20. E-commerce Integration (HIGH) ecommerce-integration - Commerce platform integration patterns 21. Content Migration (MEDIUM-HIGH) migration-patterns - Content migration strategies and tooling 22. AI Features (MEDIUM) ai-content-features - Storyblok AI capabilities and RAG preparation 23. Collaboration (MEDIUM) collaboration-realtime - Real-time editing, comments, and conflict resolution 24. Custom Apps (MEDIUM) app-custom-sidebar - Sidebar apps and tool plugins beyond field plugins Core Principles Visual Editor First
Storyblok's Visual Editor is the primary editing experience:
Always apply storyblokEditable() to components Configure the Storyblok Bridge for live editing Test components in the Visual Editor, not just code Content Delivery vs Management API API Purpose Token Cache Content Delivery Fetch content Public/Preview CDN Management CRUD operations Personal/OAuth None GraphQL Read-only queries Public/Preview CDN Framework Integration Framework SDK Special Features React @storyblok/react (v5+) useStoryblokState, RSC support, StoryblokServerComponent Vue @storyblok/vue v-editable directive Nuxt @storyblok/nuxt (v9+ for Nuxt 4) Auto-registration, useAsyncStoryblok, deep option Next.js @storyblok/react Draft mode, ISR, App Router Astro @storyblok/astro Hybrid rendering Token Security
Never expose these in client-side code:
Preview tokens (show draft content) Personal access tokens (full write access) OAuth tokens (scoped access)
Safe for client-side:
Public tokens (read-only published content) How to Use
Read individual rule files for detailed explanations and code examples:
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
Each rule file contains:
Brief explanation of why it matters Incorrect code example with explanation Correct code example with explanation Configuration tables and references Key Resources Storyblok Documentation React SDK Nuxt Module Field Plugin SDK Storyblok CLI Content Delivery API Management API