Back to Details

storyblok-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Storyblok Best Practices

Storyblok最佳实践

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.
面向AI代理和大语言模型的Storyblok CMS开发综合最佳实践指南，旨在帮助代理开发者。包含24个分类下的40条规则，按影响优先级排序，为自动化代码生成和内容架构决策提供指导。

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
在以下场景中参考本指南：
  • 设计Storyblok内容模型和组件架构
  • 将Storyblok与React、Vue、Nuxt或Next.js集成
  • 配置可视化编辑器和实时预览功能
  • 使用@storyblok/field-plugin构建自定义字段插件
  • 实现内容交付API（Content Delivery API）或管理API（Management API）
  • 通过字段或文件夹翻译设置国际化（i18n）
  • 配置Webhooks以实现缓存失效和自动化流程
  • 管理多空间架构和CI/CD工作流
  • 使用自定义解析器处理富文本字段
  • 借助Image Service优化图片和性能
  • 构建工具插件或空间插件（侧边栏应用）
  • 设置预览/生产环境

Rule Categories by Priority

按优先级排序的规则分类

PriorityCategoryImpactPrefix
1Content ModelingCRITICAL
model-
2SDK IntegrationCRITICAL
sdk-
3Visual EditorCRITICAL
editor-
4Performance & CachingCRITICAL
perf-
5Security & AuthenticationCRITICAL
security-
6Field PluginsHIGH
plugin-
7API DevelopmentHIGH
api-
8InternationalizationHIGH
i18n-
9Next.js IntegrationHIGH
nextjs-
10Nuxt IntegrationHIGH
nuxt-
11App DevelopmentHIGH
app-
12Space & Asset ManagementHIGH
space-
13Webhooks & AutomationMEDIUM-HIGH
webhook-
14Workflows & PublishingMEDIUM-HIGH
workflow-
15CLI & DevOpsMEDIUM
cli-
16Testing & QualityMEDIUM
test-
17Rich Text & MediaMEDIUM
richtext-
18Common PatternsHIGH
pattern-
19SEO & Structured DataHIGH
seo-
20E-commerce IntegrationHIGH
ecommerce-
21Content MigrationMEDIUM-HIGH
migration-
22AI FeaturesMEDIUM
ai-
23CollaborationMEDIUM
collaboration-
24Custom AppsMEDIUM
app-
优先级分类影响程度前缀
1内容建模关键
model-
2SDK集成关键
sdk-
3可视化编辑器关键
editor-
4性能与缓存关键
perf-
5安全与认证关键
security-
6字段插件高
plugin-
7API开发高
api-
8国际化高
i18n-
9Next.js集成高
nextjs-
10Nuxt集成高
nuxt-
11应用开发高
app-
12空间与资产管理高
space-
13Webhooks与自动化中高
webhook-
14工作流与发布中高
workflow-
15CLI与DevOps中
cli-
16测试与质量中
test-
17富文本与媒体中
richtext-
18通用模式高
pattern-
19SEO与结构化数据高
seo-
20电商集成高
ecommerce-
21内容迁移中高
migration-
22AI功能中
ai-
23协作功能中
collaboration-
24自定义应用中
app-

Quick Reference

快速参考

1. Content Modeling (CRITICAL)

1. 内容建模（关键）

  • 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)
  • model-component-structure
    - 遵循原子设计构建组件
  • model-field-configuration
    - 配置带验证规则的字段类型
  • model-block-nesting
    - 通过限制规则管理块嵌套
  • model-naming-conventions
    - 使用统一命名规范（snake_case）

2. SDK Integration (CRITICAL)

2. SDK集成（关键）

  • sdk-storyblok-editable
    - Always apply storyblokEditable() to components
  • sdk-component-registration
    - Register all components globally
  • sdk-richtext-rendering
    - Render rich text with custom resolvers
  • sdk-storyblok-editable
    - 始终为组件应用storyblokEditable()
  • sdk-component-registration
    - 全局注册所有组件
  • sdk-richtext-rendering
    - 使用自定义解析器渲染富文本

3. Visual Editor (CRITICAL)

3. 可视化编辑器（关键）

  • editor-bridge-setup
    - Configure Storyblok Bridge correctly
  • editor-draft-published
    - Handle draft/published content properly
  • editor-bridge-setup
    - 正确配置Storyblok Bridge
  • editor-draft-published
    - 妥善处理草稿/已发布内容

4. Performance & Caching (CRITICAL)

4. 性能与缓存（关键）

  • 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
  • perf-image-optimization
    - 使用Image Service实现优化交付
  • perf-cache-invalidation
    - 结合cv参数实现合理的缓存失效
  • perf-monitoring
    - API与内容性能监控

5. Security & Authentication (CRITICAL)

5. 安全与认证（关键）

  • security-token-handling
    - Secure API token management
  • security-roles-permissions
    - RBAC and access control configuration
  • security-token-handling
    - 安全管理API令牌
  • security-roles-permissions
    - 配置RBAC与访问控制

6. Field Plugins (HIGH)

6. 字段插件（高）

  • plugin-field-development
    - Build field plugins with @storyblok/field-plugin SDK
  • plugin-field-development
    - 使用@storyblok/field-plugin SDK构建字段插件

7. API Development (HIGH)

7. API开发（高）

  • 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
  • api-content-delivery
    - 结合分页功能正确使用内容交付API
  • api-graphql
    - 使用GraphQL API实现优化查询
  • api-management
    - 使用管理API执行增删改查操作

8. Internationalization (HIGH)

8. 国际化（高）

  • i18n-field-translation
    - Implement field-level translations correctly
  • i18n-folder-level
    - Folder-level translations with Dimensions app
  • i18n-field-translation
    - 正确实现字段级翻译
  • i18n-folder-level
    - 通过Dimensions应用实现文件夹级翻译

9. Next.js Integration (HIGH)

9. Next.js集成（高）

  • nextjs-app-router
    - Integrate with Next.js App Router and RSC
  • nextjs-app-router
    - 与Next.js App Router和RSC集成

10. Nuxt Integration (HIGH)

10. Nuxt集成（高）

  • nuxt-integration
    - Configure @storyblok/nuxt module correctly
  • nuxt-integration
    - 正确配置@storyblok/nuxt模块

11. App Development (HIGH)

11. 应用开发（高）

  • app-tool-plugins
    - Build tool and space plugins with App Bridge
  • app-tool-plugins
    - 使用App Bridge构建工具和空间插件

12. Space & Asset Management (HIGH)

12. 空间与资产管理（高）

  • space-asset-management
    - Organize assets and datasources
  • space-multi-environment
    - Multi-space architecture for enterprise
  • space-asset-management
    - 管理资产与数据源
  • space-multi-environment
    - 面向企业的多空间架构

13. Webhooks & Automation (MEDIUM-HIGH)

13. Webhooks与自动化（中高）

  • webhook-configuration
    - Configure webhooks for content events
  • webhook-configuration
    - 为内容事件配置Webhooks

14. Workflows & Publishing (MEDIUM-HIGH)

14. 工作流与发布（中高）

  • workflow-releases
    - Use Releases for scheduled publishing
  • workflow-pipelines
    - Pipeline stages for content staging
  • workflow-releases
    - 使用Releases功能实现定时发布
  • workflow-pipelines
    - 为内容 staging 设置流水线阶段

15. CLI & DevOps (MEDIUM)

15. CLI与DevOps（中）

  • cli-component-sync
    - Use CLI for component schema management
  • cli-component-sync
    - 使用CLI管理组件架构

16. Testing & Quality (MEDIUM)

16. 测试与质量（中）

  • test-preview-environments
    - Set up preview and production environments
  • test-unit-integration
    - Unit, integration, and E2E testing strategies
  • test-preview-environments
    - 设置预览与生产环境
  • test-unit-integration
    - 单元测试、集成测试与E2E测试策略

17. Rich Text & Media (MEDIUM)

17. 富文本与媒体（中）

  • richtext-media-handling
    - Handle rich text media correctly
  • richtext-media-handling
    - 正确处理富文本媒体

18. Common Patterns (HIGH)

18. 通用模式（高）

  • 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
  • pattern-typescript
    - 生成并使用TypeScript类型
  • pattern-error-handling
    - 实现健壮的错误处理机制
  • pattern-debugging
    - 调试与故障排除指南
  • pattern-relations-references
    - 故事链接、关联与引用解析

19. SEO & Structured Data (HIGH)

19. SEO与结构化数据（高）

  • seo-structured-data
    - JSON-LD, Open Graph, and sitemap configuration
  • seo-structured-data
    - JSON-LD、Open Graph与站点地图配置

20. E-commerce Integration (HIGH)

20. 电商集成（高）

  • ecommerce-integration
    - Commerce platform integration patterns
  • ecommerce-integration
    - 电商平台集成模式

21. Content Migration (MEDIUM-HIGH)

21. 内容迁移（中高）

  • migration-patterns
    - Content migration strategies and tooling
  • migration-patterns
    - 内容迁移策略与工具

22. AI Features (MEDIUM)

22. AI功能（中）

  • ai-content-features
    - Storyblok AI capabilities and RAG preparation
  • ai-content-features
    - Storyblok AI功能与RAG准备

23. Collaboration (MEDIUM)

23. 协作功能（中）

  • collaboration-realtime
    - Real-time editing, comments, and conflict resolution
  • collaboration-realtime
    - 实时编辑、评论与冲突解决

24. Custom Apps (MEDIUM)

24. 自定义应用（中）

  • app-custom-sidebar
    - Sidebar apps and tool plugins beyond field plugins
  • app-custom-sidebar
    - 字段插件之外的侧边栏应用与工具插件

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
Storyblok的可视化编辑器是主要的编辑体验：
  • 始终为组件应用
    storyblokEditable()
  • 正确配置Storyblok Bridge以支持实时编辑
  • 在可视化编辑器中测试组件，而不只是在代码中测试

Content Delivery vs Management API

内容交付API vs 管理API

APIPurposeTokenCache
Content DeliveryFetch contentPublic/PreviewCDN
ManagementCRUD operationsPersonal/OAuthNone
GraphQLRead-only queriesPublic/PreviewCDN
API用途令牌缓存
内容交付API获取内容公开/预览令牌CDN缓存
管理API增删改查操作个人/OAuth令牌无缓存
GraphQL API只读查询公开/预览令牌CDN缓存

Framework Integration

框架集成

FrameworkSDKSpecial 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
框架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
混合渲染

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)
切勿在客户端代码中暴露以下令牌：
  • 预览令牌（用于展示草稿内容）
  • 个人访问令牌（拥有完整写入权限）
  • OAuth令牌（权限范围受限）
可安全用于客户端的令牌：
  • 公开令牌（仅能读取已发布内容）

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
阅读单个规则文件获取详细说明和代码示例：
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

关键资源