How to Migrate from WordPress to Sanity: Step-by-Step Process

WordPress has powered a huge part of the web for two decades, but many teams eventually hit its limits: slow page loads, plugin conflicts, security patches, and content that's tightly locked to a single theme. That's why more businesses are moving to a headless setup, and Sanity is one of the most flexible options for it.

This guide walks through the full WordPress to Sanity migration process: planning, content modeling, exporting, transforming, importing, and launching without losing your SEO. Whether you're a solo Sanity developer or a Sanity development team managing a large Sanity project, the steps below will help you avoid the most common migration mistakes.

Why Migrate from WordPress to Sanity?

Before you start, be clear on what you're actually solving. Common reasons teams move to Sanity include:

• Structured content: Sanity stores content as structured data, not HTML tied to a theme, so the same content can power your website, app, and other channels.
• Frontend freedom: You can build with Next.js, Astro, Remix, or any framework instead of being limited to PHP themes.
• Performance: A decoupled frontend can be statically generated or edge-rendered, which usually improves speed and Core Web Vitals.
• Reduced maintenance: No plugin update chains or theme conflicts to manage on the content side.
• Better editing experience: Sanity Studio is fully customizable, so editors see fields and workflows built around your content, not generic post screens.

Migration isn't always the right call. If your site is a simple blog with light traffic and no developer resources, WordPress may still serve you well. Sanity makes the most sense when content flexibility and frontend control matter.

Step 1: Audit Your Existing WordPress Site

Start by taking inventory. List every content type on your site:

• Posts and pages
• Custom post types (e.g., case studies, team members, products)
• Categories, tags, and custom taxonomies
• Media library assets
• Authors and users
• Custom fields (ACF or similar)
• Menus, redirects, and SEO metadata (Yoast, Rank Math)

Also decide what not to migrate. Old drafts, unused media, and outdated pages

are good candidates for cleanup. A migration is the best time to remove dead weight.

Step 2: Plan Your Sanity Content Model

This is the most important step, and where an experienced Sanity expert adds the most value. Don't just copy WordPress's structure one-to-one. Think about how your content should be organized.

A typical mapping looks like this:

Define these as schemas in your Sanity Studio before importing anything. Getting the schema right early prevents painful rework later.

Step 3: Set Up Sanity Studio

Create a new Sanity project and Studio:

npm create sanity@latest

Follow the prompts, choose your dataset name, and define your schema types in the schemaTypes folder. Use a separate dataset (for example, staging) for migration testing, so you never risk overwriting production content.

Step 4: Export Your WordPress Content

You have two main options for getting content out of WordPress:

Option A: WordPress export file (WXR) Go to Tools → Export in your WordPress dashboard and export all content as an XML file. This is simple and works well for smaller sites.

Option B: WordPress REST API Your site exposes content at /wp-json/wp/v2/posts, /pages, /media, and more. This approach gives you more control, handles custom post types and fields, and is better for large sites since you can fetch data in pages and filter what you need.

For custom fields, you may need to expose them through the REST API (ACF has an option for this) or fetch them separately.

Step 5: Transform Content for Sanity

Sanity doesn't store content as raw HTML. It uses Portable Text, a JSON-based rich text format. So your migration script needs to convert WordPress HTML into Portable Text blocks.

The usual approach:

1. Write a Node.js script that reads your exported data.
2. Convert HTML body content to Portable Text using @portabletext/block-tools.
3. Map WordPress fields to your Sanity schema fields.
4. Convert authors and categories into their own documents and replace references with Sanity _ref links.
5. Generate a stable _id for each document (for example, post-123 based on the WordPress ID). This lets you re-run the script safely without creating duplicates.

A simplified example of the output shape:

{
  "_id": "post-123",
  "_type": "post",
  "title": "My Blog Post",
  "slug": { "_type": "slug", "current": "my-blog-post" },
  "publishedAt": "2025-01-15T10:00:00Z",
  "author": { "_type": "reference", "_ref": "author-7" },
  "body": [ /* Portable Text blocks */ ]
}

Custom HTML, shortcodes, and page-builder content (Elementor, Divi) are the trickiest parts. Expect to write custom rules or handle some pages manually.

Step 6: Migrate Images and Media

Images need separate handling. For each media file:

1. Download it from your WordPress site.
2. Upload it to Sanity using the client's asset upload method.
3. Store the returned asset reference in your document's image field.
4. Replace inline image URLs inside your body content with Portable Text image blocks.

Keep a mapping of old WordPress media IDs to new Sanity asset IDs. You'll need it to fix references across posts. Preserve alt text, since it matters for both accessibility and SEO.

Step 7: Import Content into Sanity

Once your data is transformed, you can import it in one of two ways:

• Bulk import: Write your documents to an NDJSON file and run:

sanity dataset import content.ndjson staging

• Client-based import: Use @sanity/client in a script to create documents in batches with transactions. This is useful when you're uploading assets and creating documents in the same run.

Always import to a staging dataset first. Check counts, spot-check documents in Studio, and verify references before touching production.

Step 8: Rebuild the Frontend

With content in Sanity, your frontend fetches it using GROQ (Sanity's query language) or GraphQL. Popular choices include Next.js, Astro, and Nuxt.

Things to rebuild or verify:

• Page templates and routing that match your existing URL structure
• Portable Text rendering for headings, lists, links, images, and embeds
• Navigation, footer, and global settings
• Preview mode so editors can see drafts before publishing
• Forms, search, and any features that relied on WordPress plugins

Step 9: Protect Your SEO

Many migrations lose traffic because SEO details get missed. Before launch:

• Keep URLs the same where possible. If URLs must change, set up 301 redirects from every old URL to its new equivalent.
• Migrate meta titles and descriptions from Yoast or Rank Math into your Sanity SEO fields.
• Carry over canonical tags, Open Graph data, and structured data.
• Generate a new XML sitemap and submit it in Google Search Console.
• Check internal links so none point to old WordPress URLs.
• Crawl both sites (old and new) with an SEO crawler and compare URL lists to catch missing pages.

Step 10: Test, Launch, and Monitor

Before going live:

1. Compare document counts between WordPress and Sanity.
2. Review a sample of posts, pages, and custom types for formatting issues.
3. Test on mobile and across browsers.
4. Check page speed and Core Web Vitals.
5. Train editors on the new Studio workflow.

At launch, switch DNS or deploy the new frontend, keep WordPress available for a short period as a fallback, and monitor Search Console for crawl errors, 404s, and indexing changes over the following weeks.

Common Migration Mistakes to Avoid

• Copying the WordPress structure blindly instead of designing a proper content model
• Ignoring redirects, which leads to lost rankings and broken backlinks
• Skipping a staging dataset and testing directly on production
• Underestimating page-builder content, which rarely converts cleanly
• Forgetting editor training, which slows adoption after launch
• Not keeping WordPress data backed up until the migration is fully verified

How Long Does a WordPress to Sanity Migration Take?

It depends on scope. A small site with a few dozen pages can be migrated in a couple of weeks. A large site with thousands of posts, custom post types, complex fields, and a frontend rebuild can take several months. Content volume matters less than complexity: custom fields, page-builder layouts, and integrations are what stretch timelines.

Final Thoughts

Moving from WordPress to Sanity is more than a content transfer. It's a chance to rethink how your content is structured, delivered, and managed. With careful planning, a solid schema, a repeatable migration script, and a proper SEO checklist, you can move without losing rankings and end up with a faster, more flexible platform.

If your migration involves complex content, large volumes, or tight deadlines, working with an experienced Sanity development agency can save time and reduce risk.

Planning a WordPress to Sanity migration?

At RW Infotech, we're a certified Sanity partner with hands-on experience delivering Sanity projects, including migrations from WordPress and other legacy platforms. Our Sanity development team handles everything from content modeling and migration scripting to frontend builds and SEO-safe launches. You can see how we work in our case studies.

Looking for a Sanity expert to guide your migration? Get in touch with our team and we'll help you plan the right approach for your Sanity project.