How I migrate WordPress to Sanity + Next.js: a technical walkthrough

Migrating WordPress to Sanity + Next.js is mostly a data engineering problem. The decisions around whether to migrate are covered elsewhere — this post is purely about the mechanics: getting content out of WordPress, shaping it into typed Sanity documents, and making sure Google never sees a broken URL.

I'll walk through the four stages I use on every migration: export, schema mapping, import scripting, and redirect wiring.

Exporting WordPress content

WordPress gives you two export paths. The WXR (WordPress eXtended RSS) XML file you get from Tools → Export is fine for small sites, but it serialises everything into one flat file and the HTML inside <content:encoded> nodes is a pain to parse. I prefer the REST API for anything above a few hundred posts.

For a typical site with posts, pages, and categories I pull:

https://old-site.com/wp-json/wp/v2/posts?per_page=100&page=1
https://old-site.com/wp-json/wp/v2/pages?per_page=100&page=1
https://old-site.com/wp-json/wp/v2/categories?per_page=100
https://old-site.com/wp-json/wp/v2/media?per_page=100

I paginate through all of them and write each collection to a local JSON file. The media endpoint is worth fetching separately — it gives you source_url, alt_text, and mime_type for every attachment, which you need for image migration.

One gotcha: custom post types registered by plugins won't appear under /wp/v2/posts. Check wp-json/wp/v2 for the full namespace list and add any CPTs you find.

Mapping WordPress types to Sanity schemas

WordPress has a flat mental model: everything is a post with a post type. Sanity wants explicit document types with typed fields. I do the mapping on paper before writing a single line of import code.

Typical equivalences:

| WordPress | Sanity document type | |---|---| | post | blogPost | | page | page | | category | category | | tag | tag | | attachment | inlined as image field or figure block |

The Sanity schemas for blogPost and category look like this in my projects:

// sanity/schemas/blogPost.ts
import { defineType, defineField } from 'sanity'
 
export const blogPostSchema = defineType({
  name: 'blogPost',
  title: 'Blog post',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string', validation: Rule => Rule.required() }),
    defineField({ name: 'slug', type: 'slug', options: { source: 'title' } }),
    defineField({ name: 'publishedAt', type: 'datetime' }),
    defineField({
      name: 'categories',
      type: 'array',
      of: [{ type: 'reference', to: [{ type: 'category' }] }],
    }),
    defineField({
      name: 'excerpt',
      type: 'text',
      rows: 3,
    }),
    defineField({
      name: 'body',
      type: 'array',
      of: [{ type: 'block' }, { type: 'image' }],
    }),
    defineField({
      name: 'seo',
      type: 'object',
      fields: [
        defineField({ name: 'metaTitle', type: 'string' }),
        defineField({ name: 'metaDescription', type: 'text', rows: 2 }),
        defineField({ name: 'canonicalUrl', type: 'url' }),
        defineField({ name: 'legacySlug', type: 'string' }), // stores original WP slug
      ],
    }),
  ],
})

Notice seo.legacySlug. I always store the original WordPress slug on every document. It makes the redirect matrix trivial to generate later.

Writing the import script

The import script has three jobs: upload images to Sanity's asset store, convert HTML body content to Portable Text, and create the documents.

I use @sanity/client directly and the sanity-block-content-to-hyperscript / html-to-portable-text ecosystem. The cleanest library I've found for the HTML conversion is @portabletext/html-input — but it's new and the API shifts. A more stable option is running the WordPress HTML through htmlparser2 and mapping nodes manually. For most blog content the tags involved are limited enough that a manual mapper is 100 lines and fully predictable.

// scripts/migrate.ts
import { createClient } from '@sanity/client'
import { JSDOM } from 'jsdom'
import fs from 'node:fs'
 
const client = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: 'production',
  apiVersion: '2024-06-01',
  token: process.env.SANITY_WRITE_TOKEN!,
  useCdn: false,
})
 
const wpPosts: WpPost[] = JSON.parse(fs.readFileSync('./export/posts.json', 'utf8'))
const wpMedia: Record<number, WpMedia> = JSON.parse(fs.readFileSync('./export/media-map.json', 'utf8'))
 
async function uploadImage(sourceUrl: string, altText: string) {
  const res = await fetch(sourceUrl)
  const buffer = Buffer.from(await res.arrayBuffer())
  return client.assets.upload('image', buffer, {
    filename: sourceUrl.split('/').pop(),
    description: altText,
  })
}
 
function htmlToBlocks(html: string): PortableTextBlock[] {
  const dom = new JSDOM(html)
  const blocks: PortableTextBlock[] = []
  for (const node of dom.window.document.body.children) {
    const tag = node.tagName.toLowerCase()
    const text = node.textContent ?? ''
    if (['p', 'h2', 'h3', 'h4', 'blockquote'].includes(tag)) {
      blocks.push({
        _type: 'block',
        _key: crypto.randomUUID(),
        style: tag === 'p' ? 'normal' : tag,
        children: [{ _type: 'span', _key: crypto.randomUUID(), text, marks: [] }],
        markDefs: [],
      })
    }
    // extend: handle <ul>, <ol>, <figure> etc.
  }
  return blocks
}
 
async function run() {
  for (const post of wpPosts) {
    const featuredMedia = post.featured_media ? wpMedia[post.featured_media] : null
    let featuredImageRef = null
    if (featuredMedia) {
      const asset = await uploadImage(featuredMedia.source_url, featuredMedia.alt_text)
      featuredImageRef = { _type: 'image', asset: { _type: 'reference', _ref: asset._id } }
    }
 
    const doc = {
      _type: 'blogPost',
      _id: `wp-post-${post.id}`,
      title: post.title.rendered,
      slug: { _type: 'slug', current: post.slug },
      publishedAt: post.date_gmt,
      excerpt: post.excerpt.rendered.replace(/<[^>]+>/g, '').trim(),
      body: htmlToBlocks(post.content.rendered),
      featuredImage: featuredImageRef,
      seo: {
        legacySlug: post.slug,
        canonicalUrl: post.link,
      },
    }
 
    await client.createOrReplace(doc)
    console.log(`Imported: ${post.slug}`)
  }
}
 
run().catch(console.error)

A few things worth noting here. I prefix _id with wp-post- so re-running the script is idempotent — createOrReplace won't create duplicates. I upload images before creating the document so the reference is ready. The htmlToBlocks function above is a skeleton — you'll need to add handlers for <ul>, <ol>, <a>, <strong>, <em>, and <figure> based on what's in the actual content. Dump a sample post and audit the tags before writing the full mapper.

Run this script locally against a staging dataset first, never production. Check a random 10% of posts in Sanity Studio before promoting to production.

Preserving SEO with a 301 redirect matrix

WordPress URLs are usually /year/month/post-slug/ or just /post-slug/ depending on the permalink setting. Next.js App Router typically uses /blog/[slug]. That's a different path structure, so every old URL needs a 301.

After the import is done I query Sanity for every legacySlug and the new slug in one GROQ query:

// GROQ query to generate redirect map
*[_type == "blogPost"] {
  "from": seo.legacySlug,
  "to": slug.current
}

I export that as a JSON array and write it into next.config.ts as static redirects for small sites, or into a middleware lookup for large ones. The next.config.ts approach is simpler and gets baked into the Vercel edge config:

// next.config.ts — for sites with < 1000 legacy URLs
import type { NextConfig } from 'next'
import redirectMap from './redirects.json' // generated from GROQ export
 
const config: NextConfig = {
  async redirects() {
    return redirectMap.map(({ from, to }) => ({
      source: `/${from}`,           // e.g. /old-post-slug
      destination: `/blog/${to}`,    // e.g. /blog/new-post-slug
      permanent: true,
    }))
  },
}
 
export default config

For sites with category archives at /category/[slug]/ I build the same matrix for category documents. WordPress tag pages at /tag/[slug]/ usually don't need preserving unless they have inbound links — check Search Console before deciding.

Once the redirects are live I submit a new sitemap via Search Console and run a crawl with Screaming Frog to verify there are no chains (301 → 301) and no 404s. Category and pagination pages from WordPress that have no equivalent in the new site should redirect to the nearest logical parent — usually /blog or /.

The whole migration for a 300-post blog typically takes two focused days: half a day on export and schema design, half a day on the import script, and one day on redirect audit and staging QA.