If you've ever attempted to migrate a large-scale enterprise content management system, you know it's not just a technical project—it's an organizational transformation that tests every assumption about how content should be structured, managed, and delivered. Having recently completed a major Adobe Experience Manager (AEM) to Sanity migration, I've gained hard-won insights that go far beyond the documentation and marketing materials.
Here are ten lessons that emerged from the trenches of replatforming thousands of pages, restructuring content models, and fundamentally rethinking how content operations should work in a modern digital ecosystem.
Lesson 1: Content Audits Are Non-Negotiable, But They're Also Never Complete
Every migration guide tells you to start with a content audit. What they don't tell you is that your audit will be simultaneously too detailed and not detailed enough.
We discovered that AEM's page-centric architecture had encouraged content teams to build sprawling page hierarchies with deeply nested components. What looked like 5,000 pages in the CMS was actually closer to 15,000 content fragments when you accounted for all the embedded components, experience fragments, and asset references.
The key insight: Don't just count pages. Map content relationships, identify reusable patterns, and understand the difference between presentation structure (how AEM organized it) and content structure (what the content actually represents). We found that roughly 40% of our "pages" were actually reusable content components masquerading as standalone pages because AEM made it easier to create a new page than to build a proper content fragment.
Action item: Create a content taxonomy before you start modeling schemas in Sanity. Identify what's truly unique versus what's the same content presented differently.
Lesson 2: The Schema Is Your New Content Contract—Design It Carefully
Coming from AEM's rigid template system, Sanity's schema flexibility feels liberating. But that freedom can become a liability if you don't establish clear content modeling principles upfront.
We made the mistake of letting our initial schemas mirror AEM's component structure too closely. This created "page builder" schemas in Sanity that defeated the entire purpose of structured content. Three months into production, we realized we were still thinking in pages rather than content entities.
The breakthrough came when we adopted a COPE (Create Once, Publish Everywhere) mindset. Instead of building a "hero section" schema, we built "product," "feature," and "testimonial" schemas. The hero section became a composition of these reusable content types, not a monolithic block.
Critical decision: Flat is better than nested for content relationships. Use references instead of deeply nested objects. Your GROQ queries will thank you, and content reuse will skyrocket.
Lesson 3: Portable Text Is Brilliant, But HTML Migration Is Brutal
AEM stores rich text as HTML. Sanity uses Portable Text, a JSON-based format that's presentation-agnostic and infinitely more flexible. The transformation between these formats was our single largest technical challenge.
Converting 100,000+ HTML blocks to Portable Text required custom transformation scripts that handled edge cases we never anticipated: malformed HTML from decades of content updates, inline styles that violated our design system, and editor-inserted `<div>` wrappers that had no semantic meaning.
We built a transformation pipeline with multiple passes: sanitize HTML, convert to intermediary AST (Abstract Syntax Tree), map to Portable Text blocks, validate output, flag manual review cases. Even then, we needed content editors to manually review about 15% of migrated content.
Pro tip: Build your HTML-to-Portable-Text transformer early and test it continuously. Don't wait until migration week. We found that running incremental test migrations weekly helped us catch transformation issues before they became production problems.
Lesson 4: Asset Management Needs Its Own Migration Strategy
AEM's Digital Asset Management (DAM) is powerful but proprietary. Images have metadata, focal points, crops, and relationships that don't map 1:1 to Sanity's asset model.
We discovered that AEM had encouraged content teams to upload multiple versions of the same image at different resolutions, resulting in massive duplication. One product shot existed in 47 different sizes across the AEM DAM. In Sanity, we uploaded the master asset once and used image transformation parameters for responsive delivery.
The asset migration became an opportunity for data normalization. We implemented deduplication algorithms that identified visually similar images and consolidated them. This reduced our total asset count by 60% while actually improving content quality.
Critical infrastructure: Use Sanity's asset pipeline and CDN from day one. Hotspot and crop data can be programmatically set during migration using asset metadata from AEM.
Lesson 5: References Are Your Superpower—Use Them Liberally
AEM's content references are rigid and hierarchical. Sanity's reference system is flexible and graph-like. This difference fundamentally changes how you structure content.
In AEM, we had product pages that embedded testimonials. In Sanity, we created testimonial documents that could be referenced by products, blog posts, landing pages—any content type. This single change increased testimonial reuse from 1.2x (each testimonial used on average 1.2 pages) to 4.7x (each testimonial appearing across nearly 5 different content contexts).
The schema pattern we adopted: if content appears more than twice, make it a referenceable document type, not a nested object. This applies to authors, categories, products, features, locations—anything that represents a discrete entity.
Warning: Don't over-reference. We initially made even button labels into references, which created unnecessary complexity. The rule of thumb: reference entities, embed attributes.
Lesson 6: Content Freeze Strategies Must Account for Business Reality
Theory says you implement a content freeze during migration. Reality says your marketing team has a product launch scheduled for exactly the same week, and executives won't delay it for "IT infrastructure changes."
We developed a dual-publishing strategy: content continued flowing into AEM while we ran parallel migrations nightly, syncing changes from AEM to our staging Sanity dataset. This required custom change detection scripts that identified modified content in AEM and re-migrated only those items.
The final cutover happened over a weekend with a true content freeze, but only for 36 hours instead of the originally planned two weeks. The continuous sync strategy kept our Sanity dataset 90% current throughout the project.
Technical requirement: Build idempotent migration scripts that can safely run multiple times. Sanity's migration tooling supports this pattern, but you need to design for it from the start.
Lesson 7: Preview Environments Are Mission-Critical for Stakeholder Buy-In
Content editors didn't trust Sanity until they could see their content rendered in context. We built Presentation and live preview integration early—probably the single best decision we made for change management.
Being able to show content teams that they could click directly from the preview into the Studio field that needed editing eliminated 90% of the "we can't do this in the new system" objections. The visual editing experience, where editors work directly on the page, made the transition feel less like learning a new CMS and more like a UI refresh.
Set up preview environments for staging and production. Use Sanity's Presentation tool with proper secret handling so previews work across your entire content model, not just blog posts.
Lesson 8: Team Training Is a Content Problem, Not a Technical One
We initially planned technical training sessions: "Here's how schemas work, here's GROQ, here's document relationships." Content teams glazed over within 15 minutes.
What worked was content-centric training: "Here's how you publish a product page, here's how you update the homepage hero, here's how you add a new testimonial and have it appear automatically on relevant pages." We built video tutorials for every common content workflow and embedded them directly in the Studio as help text.
The breakthrough was creating a "content playbook" document type in Sanity itself. Every content pattern had documentation with screenshots, living right in the CMS where editors worked. Need to know how to create a comparison table? There's a playbook article with examples you can duplicate.
Change management: Content editors need task-based training, not system architecture explanations. Focus on workflows, not features.
Lesson 9: Performance Wins Come from Architecture, Not Optimization
AEM's Dispatcher cache configuration was a constant battle. Invalidation strategies, cache warming, edge cases where content didn't update—we spent countless hours optimizing something that was fundamentally flawed.
Sanity's API-first architecture with proper CDN integration eliminated these issues entirely. Content updates propagate to the edge in seconds. GROQ queries are fast by default. Static site generation (we used Next.js) meant most pages never hit Sanity's API in production—they were pre-rendered at build time.
The shocking result: page load times dropped from 3-4 seconds to under 1 second. But more importantly, the development velocity increased because we weren't constantly debugging cache invalidation problems.
Architecture choice: Pair Sanity with modern Jamstack deployment (Vercel, Netlify or our favorite Cloudflare Pages). The combination of Sanity's content API and edge-first rendering is transformative for performance.
Lesson 10: Migration Is Not a Destination—It's the Start of Continuous Evolution
The most important lesson: treating migration as a project with an end date is a mistake. What we learned is that moving to Sanity enables continuous content model evolution in a way AEM never did.
In AEM, schema changes required Java development, extensive testing, and careful deployment orchestration. In Sanity, we can modify schemas through pull requests, test changes in preview environments, and deploy updates without downtime. This has fundamentally changed our relationship with the content model.
Post-migration, we've made 47 schema updates in six months—adding new content types, refining existing ones, deprecating outdated patterns. Each change was incremental, tested, and deployed safely. This would have been impossible in AEM without major version upgrades.
Cultural shift: Your content model should evolve with your business needs. Sanity's migration tooling and git-based workflows make this possible. Embrace continuous improvement rather than "get it right once."
The Real ROI: Speed, Flexibility, and Team Empowerment
Looking back at the migration, the technical challenges were significant but surmountable. The real transformation was organizational: content teams that were dependent on developers for every change are now self-sufficient. Features that would have taken months in AEM ship in days. The total cost of ownership dropped by 65% when you factor in Adobe licensing, infrastructure, and development overhead.
But perhaps most importantly, we stopped thinking about "the website" as a single entity. With Sanity's omnichannel approach, the same content powers our web presence, mobile apps, digital signage, and partner integrations. Content has become a true business asset, not just website filler.
If you're considering a similar migration, my advice is simple: focus on content modeling before code, invest heavily in stakeholder education, and remember that the migration is just the beginning of a much more interesting content journey.
The AEM-to-Sanity migration taught us that the future of content management isn't about bigger, more feature-rich monoliths—it's about composable, structured content that can adapt as quickly as your business needs to evolve.
