Disclosure
Executive Summary
In early 2024, I embarked on a significant content infrastructure project to migrate ramp.com from Webflow to Sanity CMS. With over 1,500 documents, custom embeds, and complex content relationships, this migration presented substantial technical challenges.
This case study documents my journey, technical approach, and key learnings to help teams considering a similar migration path.
Project Background
As the lead architect behind the migration, I encountered a persistent challenge: while Webflow had served Ramp well initially, the growing content needs of a scaling fintech organization demanded more flexibility, customization, and developer control than Webflow could provide.
The existing setup faced several limitations:
- Limited customization for complex content models
- No structured content approach for reusable components
- Inadequate support for reference relationships between content types
- Editor experience issues when managing large volumes of content
- Challenges with custom embeds and widgets in blog content
- Poor page performance, due to no ability to server side render pages or tree-shake unused code
With rapidly expanding content initiatives including new specialized blogs planned for 2025, it became clear that a more powerful, developer-friendly CMS solution was needed.
Why Sanity CMS?
After evaluating several headless CMS options, we selected Sanity for several key reasons:
Content Flexibility
Sanity's schema-based approach and Portable Text format offered unparalleled flexibility for structuring complex content types.
Developer Experience
First-class React integration and ability to customize the editing environment with JavaScript provided complete control.
Content Relationships
Reference fields and backlink capabilities allowed for sophisticated content relationships that would significantly improve content management.
Scaling Potential
Sanity's performance at scale and robust API made it suitable for an enterprise-level content operation serving hundreds of thousands of visitors.
Migration Strategy and Timeline
Rather than attempting a "big bang" migration, we implemented a phased approach that minimized risk and allowed for iterative improvements:
Initial Setup and Evaluation (Q1 2024)
We began with a proof-of-concept implementation focused on field parity with Webflow and building essential infrastructure. This phase included deploying Sanity Studio and implementing live preview functionality.
Architecture and Structure Development (Q2 2024)
We made critical architecture decisions including monorepo setup, caching strategy, and data structure approach. This phase established our technical foundation and best practices.
Custom Development (Q3 & Q4 2024)
We developed custom embeds/widgets to replace Webflow functionality, implemented bulk actions for content management, and enhanced the Sanity Studio UI for non-technical users.
Content Migration and Transition (Q1 2025)
After thorough preparation, we executed the migration of all blog content, implemented a 24-hour content freeze during the critical transition period, and successfully moved content management entirely to Sanity.
Technical Implementation
Content Modeling in Sanity
We approached content modeling with a focus on flexibility, performance, and maintainability. Key decisions included:
- Flat data structure: We kept data structures flat rather than deeply nested, which significantly improved GROQ query performance.
- Reference fields: We implemented reference fields to create relationships between content types (e.g., blog posts and authors).
- Custom object types: Instead of using raw HTML embeds, we created structured Sanity objects for custom elements like comparison widgets, CTAs, and other interactive components.
For example, here's how we approached the schema for blog posts:
1// Example blog post schema in Sanity
2export default {
3 name: 'blogPost',
4 title: 'Blog Post',
5 type: 'document',
6 fields: [
7 {
8 name: 'title',
9 title: 'Title',
10 type: 'string',
11 validation: Rule => Rule.required()
12 },
13 {
14 name: 'slug',
15 title: 'Slug',
16 type: 'slug',
17 options: {
18 source: 'title',
19 maxLength: 96
20 },
21 validation: Rule => Rule.required()
22 },
23 {
24 name: 'publishedAt',
25 title: 'Published At',
26 type: 'datetime',
27 validation: Rule => Rule.required()
28 },
29 {
30 name: 'authors',
31 title: 'Authors',
32 type: 'array',
33 of: [{ type: 'reference', to: [{ type: 'author' }] }]
34 },
35 {
36 name: 'content',
37 title: 'Content',
38 type: 'array',
39 of: [
40 { type: 'block' },
41 { type: 'comparisonAccordion' },
42 { type: 'g2Comparison' },
43 { type: 'productCta' },
44 { type: 'emailForm' },
45 { type: 'image' },
46 { type: 'table' }
47 ]
48 },
49 {
50 name: 'webflowId',
51 title: 'Webflow ID',
52 type: 'string',
53 hidden: true
54 },
55 ]
56}Migration Approach
Our migration process focused on preserving data integrity while transforming content into Sanity's structured format:
- ID preservation: We maintained reference integrity by preserving original Webflow IDs with an "imported-" prefix.
- Chunked migration: Rather than attempting to import everything at once, we chunked large collections to manage the process more effectively.
- HTML to Portable Text conversion: We converted Webflow's rich text HTML to Sanity's Portable Text format while preserving styling and structure.
- Custom embed transformation: We identified all custom embeds used across blog posts and created corresponding Sanity objects.
A critical part of our approach was running extensive tests with sample content before attempting the full migration. We also implemented a backup strategy that created snapshots every 2 days with a 14-day retention period.
Front-end Integration
We integrated Sanity with our Next.js front-end using a carefully considered caching and revalidation strategy:
- Path-based revalidation: After evaluating time-based, tag-based, and path-based approaches, we implemented path-based revalidation as our primary strategy.
- Selective API usage: We used Sanity's API CDN for most content but implemented direct API access for frequently updated collections.
- GROQ optimization: We carefully optimized our GROQ queries to maintain performance while minimizing API costs.
For image handling, we transitioned from the Sanity-specific image component to standard Next.js Image components, which provided better optimization and performance.
Challenges and Solutions
Custom Embeds Complexity
Challenge: Webflow blogs contained numerous custom embeds and widgets that needed to be recreated in Sanity's structured format.
Solution: We systematically identified all embed types across 900+ blog posts, created corresponding Sanity object schemas, and developed migration scripts to transform embedded HTML into structured objects.
Caching and Performance
Challenge: Balancing content freshness against API costs and performance presented significant challenges.
Solution: We discovered Sanity's API CDN has a 60-second TTL, which affected our revalidation strategy. We implemented path-based revalidation using webhooks to invalidate specific content paths when changes occur.
Reference Integrity
Challenge: Preserving relationships between content types (like blog posts and authors) during migration.
Solution: We preserved Webflow IDs during migration by adding an "imported-" prefix, which maintained all reference relationships while clearly identifying imported content.
Migration Timing
Challenge: Coordinating a seamless transition without disrupting ongoing content operations.
Solution: We implemented a 24-hour content freeze during the final migration phase and timed the deployment to avoid team OOO periods. This approach allowed for a controlled transition with minimal disruption.
Results and Benefits
The migration to Sanity delivered significant improvements across multiple dimensions:
Technical Benefits
- Structured content: Content is now properly structured with well-defined relationships, making it more maintainable and reusable.
- Improved editor experience: The custom Sanity Studio provides a more intuitive and efficient workflow for content creators.
- Enhanced development workflow: Monorepo architecture simplifies dependency management and streamlines development.
- Reference management: Content relationships are now explicit and traceable, with the ability to view backlinks and references.
Business Benefits
- Scalability: The content infrastructure can now support planned growth initiatives, including new specialized blogs.
- Content efficiency: Content teams can update referenced content (like product details) in one place, automatically updating all instances.
- Reduced technical debt: The migration eliminated accumulated technical debt from Webflow workarounds.
- Improved publishing workflow: Features like scheduled publishing, bulk actions, and custom field editors have streamlined content operations.
Key Learnings
Technical Insights
- Flat vs. nested data: Keeping data structures flat significantly improves GROQ query performance compared to nested structures.
- Caching considerations: Understanding Sanity's API CDN TTL (60 seconds) is crucial for designing an effective caching strategy.
- Image handling evolution: The recommended approach for images changed from specialized Sanity components to standard Next.js Image components.
- Proper staging environment: A dedicated QA dataset for testing schema changes before production implementation is essential.
Project Management Insights
- Phased migration: A collection-by-collection approach was more manageable than attempting to migrate everything at once.
- Specialist collaboration: Engaging CMS specialists (Tinloof) accelerated implementation and provided valuable best practices.
- Deployment timing: Avoiding major deployments before team OOO periods reduced unnecessary risk.
- User training: Investing in documentation and training sessions was essential for successful user adoption.
When Should You Migrate from Webflow to Sanity?
Based on our experience, these are the key indicators that it might be time to consider migrating from Webflow to Sanity:
Complex Content Relationships
When you need sophisticated content relationships and references that Webflow's CMS can't easily support.
Large Content Volume
When managing hundreds of content items becomes unwieldy in Webflow's interface and architecture.
Developer-First Approach
When you need programmatic control over your content models and editing experience.
Custom Editing Experience
When you want to create tailored editing interfaces for different content types and user roles.
Ready to Transform Your Content Infrastructure?
If you're considering migrating from Webflow to Sanity CMS, ContentWrap can guide your team through the process with insights from real-world implementation experience.
Schedule a ConsultationAbout the Author: Tamba Monrose is a senior software engineer with experience at Ramp, Coinbase, and HubSpot. He specializes in frontend development and content management systems, with particular expertise in implementing and optimizing Sanity CMS deployments.