How to Migrate from WordPress to Decoupled.io

WordPress powers a huge share of the web, and for good reason — it's easy to set up, has a massive plugin ecosystem, and content editors generally know how to use it. But if you're building a modern frontend with React or Next.js, WordPress becomes a bottleneck. The REST API is verbose and untyped. Performance depends on your hosting and your plugin stack. And keeping WordPress secure means an endless cycle of core updates, plugin patches, and PHP version upgrades.

Decoupled.io gives you a Drupal-powered CMS backend with managed hosting, a typed client for your frontend, and content modeling that WordPress can't match — while keeping the concepts your team already knows.

Why Migrate

The WordPress REST API is painful for frontend development. WP REST returns deeply nested, untyped JSON. There's no schema you can use for code generation, no autocomplete in your IDE, and no compile-time safety. You end up writing defensive code — post?.title?.rendered — and hoping the shape doesn't change when someone installs a plugin.

Self-hosted PHP is a maintenance burden. WordPress requires you to manage hosting, PHP versions, MySQL databases, SSL certificates, caching layers, and security patches. Every plugin update is a potential breaking change. Decoupled.io is fully managed — you focus on content and frontend code.

Content modeling is limited. WordPress was built for posts and pages. Custom post types and Advanced Custom Fields (ACF) get you further, but they're bolted on, not built in. Complex content structures — nested components, structured landing pages, multi-step workflows — require stacking plugins that don't always play well together. Drupal's entity-field system handles these natively.

What You'll Need

• A Decoupled.io account
• Access to your WordPress admin (for export) or database
• Your frontend codebase (if you have a decoupled frontend already)
• About 3-5 hours for a typical migration

Step-by-Step Migration Plan

Step 1: Audit Your WordPress Content

Before migrating, inventory what you have:

• Post types — Posts, pages, and any custom post types (CPTs)
• Taxonomies — Categories, tags, and custom taxonomies
• Custom fields — ACF field groups, custom meta fields
• Media — Images, documents, videos in the media library
• Menus — Navigation structures
• Users — Authors and editors (if you need to preserve attribution)

This inventory tells you exactly what content types and fields to create in Decoupled.io.

Step 2: Create Content Types in Decoupled.io

Map your WordPress structures to Drupal content types. The concepts translate naturally:

If you're using ACF for structured content, you'll find Drupal's field system is more powerful out of the box — entity references, paragraphs (for page sections), and media handling are all core features, not plugins.

Step 3: Migrate Content Using Drupal's Migrate API

Drupal has a mature migration framework that can pull content directly from a WordPress database or from WP REST API endpoints. The WordPress-to-Drupal migration path is one of the most well-documented migrations in the Drupal ecosystem.

The migration handles:

• Posts and pages with full body content
• Categories and tags (including hierarchical taxonomies)
• Media files (downloaded and re-referenced)
• Authors and user attribution
• URL aliases (so your SEO URLs are preserved)

Step 4: Generate the Typed Client

With your content migrated, generate the typed client for your frontend:

npx decoupled-cli@latest schema sync

This is the biggest upgrade from WordPress development. Instead of untyped REST responses, you get TypeScript interfaces generated from your actual content model.

Step 5: Build (or Update) Your Frontend

If you already have a decoupled frontend hitting the WP REST API, replace those calls with typed client calls. If your WordPress site is a traditional theme, this is your opportunity to build a modern frontend with React, Next.js, or Astro.

What Changes in Your Frontend Code

If you've been using WordPress REST API, the typed client is a significant improvement:

Before (WordPress REST API):

const res = await fetch(
  'https://yoursite.com/wp-json/wp/v2/posts?per_page=10&_embed'
)
const posts = await res.json()

// No types — you're guessing at the shape
const title = posts[0]?.title?.rendered
const image = posts[0]?._embedded?.['wp:featuredmedia']?.[0]?.source_url
const category = posts[0]?._embedded?.['wp:term']?.[0]?.[0]?.name

After (decoupled-client):

import { createClient } from 'decoupled-client'
import { createTypedClient } from './schema/client'

const base = createClient({
  baseUrl: process.env.NEXT_PUBLIC_DRUPAL_BASE_URL!,
  clientId: process.env.DRUPAL_CLIENT_ID!,
  clientSecret: process.env.DRUPAL_CLIENT_SECRET!,
})

const client = createTypedClient(base)

const articles = await client.getEntries('NodeArticle', { first: 10 })

// Fully typed — IDE autocomplete works, typos caught at build time
const title = articles[0].title
const image = articles[0].image?.url
const category = articles[0].category?.name

No more optional chaining chains. No more _embedded lookups. No more rendered vs raw confusion. The typed client gives you clean, predictable data shapes.

What Stays the Same

• Content concepts — Posts become nodes, categories become taxonomy terms, pages stay pages. The vocabulary changes slightly, but the mental model is the same.
• Editorial workflow — Content editors use a web-based admin panel to create, edit, and publish content. Drupal's admin is different from WordPress's, but the workflow is familiar — and it includes built-in content moderation and revision history.
• Media management — Upload images and files through the admin panel. Drupal handles image styles (automatic resizing/cropping) and CDN delivery.
• SEO fundamentals — URL aliases, meta tags, and XML sitemaps are all supported. Your existing URL structure can be preserved during migration.

Next Steps

1. Get started with Decoupled.io — Set up your account, create your first space, and connect your frontend.
2. Explore pricing — Managed hosting means no more paying for PHP hosting, caching plugins, and security monitoring separately.
3. Learn the typed client — Full documentation for decoupled-client, the biggest upgrade from WordPress REST API.
4. Set up MCP for AI-assisted development — Use AI tools to scaffold content types and populate sample data.