Component Versioning Guide

Learn how Storyblok handles component versioning and how to manage component evolution.

Overview

Component versioning helps you:

Track schema changes over time
Understand component evolution
Manage multiple component versions
Plan migrations safely

How Storyblok Versioning Works

Schema Changes

Every time you modify a component schema, Storyblok increments an internal version number. This helps track when components were last changed.

Content Versions

Story content is versioned separately from components. Stories reference component schemas at the time of editing.

Versioning Strategies

Strategy 1: In-Place Updates

Update the same component, migrating content as needed.

Pros:

Single source of truth
No confusion about which to use
Simpler maintenance

Cons:

Requires content migration
Can't compare old vs new easily
Riskier changes

When to use: Minor improvements, bug fixes, adding optional fields.

Update blog_post component to add "reading_time" field:
1. Add field as optional
2. Calculate reading time for existing posts
3. Update all stories

Strategy 2: Side-by-Side Versions

Create new component version alongside old one.

Pros:

Safe migration path
Can compare versions
Gradual transition
Easy rollback

Cons:

Multiple components to maintain
Editor confusion
Need to eventually consolidate

When to use: Major changes, new features, structural changes.

Create blog_post_v2 component:
1. Clone blog_post to blog_post_v2
2. Make desired changes to v2
3. Test v2 with new content
4. Gradually migrate old content
5. Deprecate blog_post when done

Strategy 3: Feature Flags

Add optional features to existing component using boolean fields.

Add "enable_comments" boolean to blog_post:
- When true, show comments section
- When false, hide comments
- Allows gradual feature rollout

Version Naming Conventions

Explicit Versions

blog_post_v1
blog_post_v2
blog_post_v3

Clear but clutters component list.

Dated Versions

blog_post_2024
blog_post_legacy

Shows age but less precise.

Feature-Based Names

blog_post (current)
blog_post_simple (lightweight version)
blog_post_advanced (extended features)

Descriptive but can be confusing.

Migration Patterns

Gradual Migration

Migrate from hero_v1 to hero_v2:
1. Create hero_v2 component
2. Use hero_v2 for new content (month 1)
3. Migrate high-traffic pages (month 2)
4. Migrate remaining pages (month 3)
5. Deprecate hero_v1 (month 4)
6. Delete hero_v1 (month 5)

Flag Day Migration

Big bang migration:
1. Test hero_v2 thoroughly
2. Schedule migration day
3. Migrate all content at once
4. Remove hero_v1 immediately

Only for small content volumes or critical fixes.

Deprecation Process

Mark as Deprecated

For blog_post_v1 (being replaced):
1. Add "(DEPRECATED)" to display name
2. Update description: "Use blog_post_v2 instead"
3. Don't delete yet - keep for reference

Prevent New Usage

Move deprecated components to "Archived" group
Editors can't easily find them for new content
Existing content still works

Final Removal

Delete blog_post_v1 only when:
- No stories use it (verify with search)
- 30+ days since last usage
- Team has been notified
- Backup export created

Tracking Component Changes

Change Log

Keep a document tracking component changes:

# Component Changelog

## blog_post v2 (2024-02-01)
- Added reading_time field
- Changed intro from text to richtext
- Added featured_author relation

## blog_post v1 (2023-06-15)
- Initial version
- Basic blog fields

Schema Exports

Before major changes:
1. Export current component schema
2. Save as blog_post_schema_2024-01-15.json
3. Commit to version control
4. Reference in documentation

Best Practices

Version sparingly - Don't create v2 for every small change
Clear naming - Make purpose obvious
Document changes - Keep changelog
Plan migrations - Don't leave old versions forever
Test thoroughly - New versions should improve, not break
Communicate - Tell editors about new versions
Gradual rollout - Migrate incrementally when possible
Clean up - Remove deprecated versions after migration

When to Create New Version

Create New Version When:

Major structural changes
Significant field changes
Different use case
Can't migrate content easily
High risk of breaking existing content

Update In-Place When:

Adding optional fields
Fixing bugs
Improving descriptions
Minor validation changes
Low risk changes

Need help with component versions? Ask Claude to help plan your component evolution strategy!