Migrate from Sanity to Cosmic: A Complete Developer Guide

If your team has been building on Sanity and the friction is starting to outweigh the flexibility, you are not alone. GROQ is a powerful query language, but it is also one more proprietary system your team has to learn and maintain. Sanity Studio is a flexible editing environment, but it is also a React app you have to configure and deploy separately. And at scale, per-seat pricing, add-on SSO costs, and multi-dataset fees add up fast.

This guide walks you through a complete migration from Sanity to Cosmic, an AI-powered headless CMS built around a clean REST API, a hosted editing interface, and AI agents built into the platform.

Before you start, take a look at the Sanity alternative overview and the Sanity vs. Cosmic comparison to understand what you are gaining in the switch. If you have already migrated from another platform, the Contentful migration guide and Ghost migration guide follow the same structure.

---

Why Teams Migrate from Sanity to Cosmic

1. GROQ Query Complexity

GROQ (Graph-Relational Object Queries) is Sanity's custom query language. It is expressive and capable. It is also something only Sanity uses. Every developer who joins your team has to learn it from scratch, every query has to be tested in a GROQ-specific sandbox, and when you leave Sanity, that investment disappears.

Cosmic uses a clean REST API with URL query parameters and a TypeScript SDK. Standard HTTP. Concepts your team already knows. Switching developers or onboarding contractors does not require a GROQ bootcamp.

2. Per-Seat Pricing at Scale

Sanity's Growth plan is $15/seat/month. That sounds manageable for a small team, but add SSO ($1,399/month), dedicated support ($799/month), and extra datasets ($999/month each), and the cost for a mid-sized team can reach several thousand dollars a month before you hit enterprise tier.

Cosmic pricing is flat per plan:

Additional users are $29/user/month. SSO is included on the Enterprise plan.

3. Steep Learning Curve for Content Editors

Sanity Studio is powerful for developers. For non-technical content editors, it can be confusing: GROQ previews, schema-driven UI, the concept of "document references" and "portable text blocks" are all developer abstractions leaking into the editorial experience.

Cosmic's dashboard is purpose-built for both audiences. Developers define the schema. Editors fill in structured fields. The interface does not expose the underlying data model to people who should not need to know about it.

4. Cold API Performance on Sanity's Free Tier

Sanity's free tier serves content from cold API instances that can have noticeable latency on the first request after a period of inactivity. For production sites or teams testing performance, this creates misleading benchmarks.

Cosmic's API is globally distributed and warmed on all plans, including free.

---

Sanity-to-Cosmic Concept Mapping

Before writing any migration code, it helps to understand how Sanity's mental model maps onto Cosmic's.

The biggest conceptual shift: in Sanity, your schema is code (TypeScript files in your Studio). In Cosmic, your schema is configuration defined in the dashboard. This means no schema deployments, no code reviews for content model changes, and no divergence between what editors see and what is in the codebase.

---

Step-by-Step Migration Guide

Step 1: Export Sanity Content via GROQ or Dataset Export

Sanity provides two ways to export your content.

Option A: Dataset Export (recommended for full migration)

This exports everything: all documents, all drafts, all asset references. Extract the archive and you will find an file with one JSON document per line.

Option B: GROQ export via the API (selective export)

For partial migrations or when you only need specific document types:

---

Step 2: Map Sanity Schemas to Cosmic Object Types

Look at your Sanity schema files (typically in ) and create corresponding Object Types in the Cosmic dashboard.

Common Sanity field types and their Cosmic equivalents:

You can also create Object Types via the Cosmic REST API:

---

Step 3: Migrate Content Using Node.js Script with Cosmic REST API

With your Object Types created and your Sanity export ready, write a migration script.

Handling Portable Text (Sanity's Rich Text Format)

Portable Text is Sanity's structured rich text format. It stores content as a JSON array of block nodes. Before you can store it in Cosmic, you need to convert it.

Batch operations for large content sets:

For content libraries with hundreds of documents, use Cosmic's batch operations to migrate up to 25 objects at a time:

---

Step 4: Migrate Media Assets

Sanity stores assets with IDs in the format . Your dataset export includes an object mapping those IDs to CDN URLs.

Every migrated asset gets a permanent Cosmic imgix URL with on-the-fly resizing and format conversion built in. No separate CDN configuration needed.

---

Step 5: Update Front-End Queries (Remove GROQ, Use Cosmic SDK or REST API)

This is where day-to-day developer experience improves most noticeably. Replace GROQ queries and the Sanity client with Cosmic's REST API and JavaScript SDK.

Before (Sanity client + GROQ):

After (Cosmic SDK):

Using the REST API directly:

---

Step 6: Set Up Webhooks for Content Sync

Cosmic supports outgoing webhooks that fire on , , and events. Use these to trigger ISR revalidation in Next.js, rebuild jobs in Netlify or Vercel, or custom sync pipelines.

Set up a webhook in the Cosmic dashboard:

1. Go to Bucket Settings > Webhooks
2. Add your endpoint URL (e.g. )
3. Select trigger events ( is the most common)
4. Save. Webhooks are available as a $99/month add-on, or included in the $199/month bundle with Localization, Revision History, and Automatic Backups.

Next.js revalidation endpoint:

---

Framework-Specific Code Examples

Next.js (App Router)

Nuxt 3

Astro

---

Multi-Dataset to Multi-Bucket Setup

Sanity charges $999/month per additional dataset beyond the included ones. Many teams use multiple datasets for staging, production, and regional variants.

In Cosmic, each dataset is a Bucket. Each Bucket has its own API keys, content model, media library, and team members. The pricing is much more accessible:

• Builder ($49/mo): 2 Buckets
• Team ($299/mo): 3 Buckets
• Business ($499/mo): 5 Buckets
• Additional Buckets: $29/bucket/month on any paid plan

To migrate multiple Sanity datasets, run your migration script once per dataset/bucket pair:

---

Using a Cosmic Team Agent for Bulk Content Migration

For large Sanity content libraries with thousands of documents, running migration scripts manually can be slow and error-prone. Cosmic's AI Team Agents can automate bulk migration tasks directly from your Slack channel.

Here's how to set one up:

1. Create a Team Agent in your Cosmic dashboard with and capabilities enabled.
2. Write the migration prompt describing the source (your Sanity export JSON or API), the target Cosmic Object Types, and the field mappings.
3. Connect the agent to Slack. It joins your channel and accepts commands like "migrate the next 50 blog posts from the Sanity export" or "retry the 12 entries that failed."
4. Monitor progress. The agent posts status updates as batches complete, flagging entries that need manual review due to missing fields or relationship mismatches.

The agent can process entries in batches of 25 using Cosmic's batch operations API, significantly faster than running sequential single-entry scripts.

For enterprise migrations with complex Sanity schemas and large content libraries, book a call with Tony and we will scope a custom migration plan.

---

Pre-Launch Checklist

Before you cut traffic to Cosmic, run through this checklist:

Content Model

• All Sanity schemas recreated as Cosmic Object Types
• Metafield types match the original Sanity field types
• Relationship fields (, ) reference the correct Object Types
• Slug fields are set and unique across each Object Type

Content Data

• All documents migrated and spot-checked in the Cosmic dashboard
• Portable Text converted to HTML or Markdown and rendering correctly in the frontend
• Draft vs. published status set correctly for all Objects
• Author, category, and tag relationships resolving to the correct related Objects
• Published dates preserved from Sanity fields

Media

• All Sanity image assets migrated to Cosmic media library
• correctly resolves Sanity asset IDs to Cosmic imgix URLs
• Image resizing parameters (e.g. ) applied in frontend templates
• File and video assets accessible via Cosmic URLs
• text preserved for all images

API and Code

• removed from all dependencies
• Cosmic SDK installed:
• All GROQ queries replaced with Cosmic REST API or SDK calls
• and environment variables set in all environments
• Sanity environment variables (, , etc.) removed or deprecated
• or similar Portable Text renderer removed from frontend if no longer needed

Frontend

• All pages rendering correctly with Cosmic data
• Dynamic routes () working for all Object Types
• Fallback and 404 states handling missing slugs gracefully
• Open Graph and meta tags pulling from Cosmic metadata fields
• Responsive images using imgix URL parameters

SEO

• All existing URLs preserved (same slugs migrated from Sanity)
• Canonical tags correct
• Sitemap regenerated and submitted to Google Search Console
• 301 redirects set up for any slugs that changed during migration

Webhooks and Automation

• Sanity webhooks removed from hosting provider
• Cosmic webhooks configured for ISR revalidation or rebuild triggers
• Webhook endpoint authenticated and tested
• Content preview workflow tested by a non-technical team member

Testing

• Full page audit on staging environment with Cosmic data
• API response times verified under realistic load
• Content editor workflow tested end-to-end: create, publish, verify on frontend
• Rollback plan documented in case of production issues

---

Ready to Make the Switch?

Migrating from Sanity to Cosmic removes a proprietary query language from your stack, eliminates a separate Studio deployment from your infrastructure, and gives your editors a purpose-built interface they can actually use without developer help.

Most teams complete a standard migration in a few days. You come out the other side with a simpler codebase, predictable flat-rate pricing, and AI agents that automate content work rather than just assisting with it.

Explore related resources:

• Sanity alternative overview
• Sanity vs. Cosmic feature comparison
• Contentful migration guide
• Ghost migration guide
• Cosmic JavaScript SDK
• Cosmic docs

Start free, no credit card required: Sign up at cosmicjs.com

Migrating a larger team or complex Sanity schema? Book a 30-minute intro call with Tony, our CEO and we will walk through your specific setup.