storyblok-best-practices

Estrelas10

Forks2

Atualizado25 de janeiro de 2026 às 11:38

Comprehensive Storyblok CMS development best practices for agency developers. Covers content modeling, SDK integration (React, Vue, Nuxt, Next.js), Visual Editor configuration, field plugins, API usage, internationalization, webhooks, and deployment patterns. Triggers on tasks involving Storyblok components, Visual Editor setup, content fetching, field plugin development, or headless CMS integration.

Instalação

Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.

Explorador de arquivos

47 arquivos

SKILL.md

readonly

name	storyblok-best-practices
description	Comprehensive Storyblok CMS development best practices for agency developers. Covers content modeling, SDK integration (React, Vue, Nuxt, Next.js), Visual Editor configuration, field plugins, API usage, internationalization, webhooks, and deployment patterns. Triggers on tasks involving Storyblok components, Visual Editor setup, content fetching, field plugin development, or headless CMS integration.
license	MIT
metadata	{"author":"storyblok-engineering","version":"1.0.0"}

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