Why migrate from Contentful?
Common reasons for migration
| Contentful Challenge | ButterCMS Solution |
|---|---|
| Complex content modeling | Intuitive visual content type builder |
| Steep learning curve | User-friendly interface for marketers |
| Difficult bulk data imports | Write API for programmatic imports |
| Pricing scales with content | Predictable pricing with generous limits |
| Developer-heavy workflows | Balance between developer and marketer needs |
| Complex API structure | Simple, intuitive REST API |
Feature comparison
| Feature | Contentful | ButterCMS |
|---|---|---|
| Content Modeling | Content Types with complex relationships | Page Types, Collections, Components |
| Blog Engine | Must build from scratch | Built-in blog with categories, tags, authors |
| Preview | Requires setup | Built-in preview functionality |
| Localization | Available | Available with visual locale switcher |
| Components | Embedded entries | Visual Component Library |
| Migrations | CLI-based migrations | Visual migration tool (Enterprise) |
| Media | Asset management | CDN-hosted Media Library |
| API | GraphQL + REST | REST API |
Migration planning
Step 1: Audit your Contentful content
Before migrating, create an inventory of your Contentful content: Content Types to identify:- Entry types (equivalent to ButterCMS Page Types)
- Assets (equivalent to ButterCMS Media)
- Content entries (equivalent to Pages or Collection Items)
- Locales configured
- Webhooks set up
- API integrations
Contentful to ButterCMS mapping
| Contentful Concept | ButterCMS Equivalent | Notes |
|---|---|---|
| Content Type | Page Type | Define schema for pages |
| Entry | Page or Collection Item | Depends on use case |
| Asset | Media Library item | Automatic CDN hosting |
| Space | Site | One space = one ButterCMS site |
| Environment | Environment | Staging/Production environments |
| Locale | Locale | Similar localization approach |
| Embedded Entry | Component or Reference | Use Components for reusable blocks |
| Rich Text | WYSIWYG | Similar functionality |
| Reference | Reference field | One-to-One or One-to-Many |
| Array | Repeater | For lists of items |
| Link | Reference | For content relationships |
Step 2: Map content types to ButterCMS
Contentful Content Types become ButterCMS Page Types or Collections:When to use Page Types
When to use Page Types
- Content that represents a webpage
- Content with SEO requirements
- Content that needs scheduling
- Content with complex field structures
- Examples: Landing pages, product pages, case studies
When to use Collections
When to use Collections
- Reference data used across pages
- Lists of items without individual URLs
- Reusable structured data
- Examples: Categories, authors, testimonials, FAQs
When to use Blog Engine
When to use Blog Engine
- Standard blog posts with author, categories, tags
- Content that follows a blog publishing workflow
- SEO-optimized article content
Step 3: Map field types
| Contentful Field Type | ButterCMS Field Type | Migration Notes |
|---|---|---|
| Short text | Short Text | Direct mapping |
| Long text | Long Text or WYSIWYG | Choose based on formatting needs |
| Rich text | WYSIWYG | Rich text content preserved |
| Number (Integer) | Number | Direct mapping |
| Number (Decimal) | Number | Direct mapping |
| Date/Time | Date | Date fields supported |
| Location | Short Text (coordinates) | Store as formatted string or separate fields |
| Boolean | Checkbox | Direct mapping |
| JSON | Long Text | Store as JSON string |
| Media (Image) | Media | Upload to ButterCMS CDN |
| Media (File) | Media | Upload to ButterCMS CDN |
| Reference (One) | Reference (One-to-One) | Link to Page Type or Collection |
| Reference (Many) | Reference (One-to-Many) | Link to multiple items |
| Array | Repeater | For repeating sets of fields |
Migration process
Step 1: Export content from Contentful
Use the Contentful Export tool to export your content:- Content types
- Entries
- Assets
- Locales
Step 2: Create ButterCMS content structure
Before importing content, set up your ButterCMS content types:- Create Page Types matching your Contentful content types
- Create Collections for reference data
- Create Components for reusable content blocks
- Configure Locales matching your Contentful setup
Step 3: Transform and import content
Use the ButterCMS Write API to import transformed content:Step 4: Handle assets/media
Contentful assets need to be uploaded to ButterCMS:Step 5: Handle references and relationships
Contentful references need special handling:Step 6: Handle rich text content
Contentful rich text needs transformation to HTML for ButterCMS WYSIWYG:Handling specific Contentful features
Embedded entries (Components)
Contentful embedded entries map to ButterCMS Components:- Create a Component in ButterCMS matching the embedded entry structure
- When migrating, extract embedded entries from rich text
- Use Component Picker fields to allow dynamic component addition
Localization
ButterCMS provides field-level localization. Set up locales in Settings, then provide locale-specific content in API requests using locale keys in the fields object:- Set up matching locales in ButterCMS Settings
- During migration, iterate through each locale
- Use locale keys in the fields object when creating content via Write API
Webhooks
Re-create your webhook integrations in ButterCMS:- Go to Settings → Webhooks
- Add webhook endpoints
- Select events to trigger webhooks
- Update any receiving applications with new payload format
Migration script template
Post-migration checklist
- All content types created in ButterCMS
- All entries migrated successfully
- Media assets uploaded and references updated
- Localized content available in all locales
- Reference relationships working correctly
- Webhooks reconfigured
- Frontend application updated with new API calls
- Preview functionality tested
- Publishing workflow tested
- Team members trained on new interface
Differences to note
| Aspect | Contentful | ButterCMS |
|---|---|---|
| API Style | GraphQL + REST | REST only |
| Content Delivery | CDN via Content Delivery API | Global CDN built-in |
| Rate Limits | Per-second limits | Monthly API call limits |
| Preview | Preview API | Built-in preview |
| Environments | Multiple environments | Staging + Production |
| CLI | Full CLI tooling | API-first approach |