I ran into this while building out a more ambitious afterChange hook for a client project — one that triggered several secondary writes on top of the main operation. Everything worked perfectly in happy-path testing. The failure only surfaced under specific timing conditions, and by then the client-facing response had already confirmed success. That kind of silent inconsistency is hard to diagnose. Once I understood the actual mechanism, I realized it came down to one overlooked detail: what it means to pass req into a Payload operation.

Why req Is More Than Request Metadata

In Payload, req carries transactional context. When you pass it into an internal operation like req.payload.create({ req, ... }), you are not just routing the request through the system — you are attaching that operation to the same database transaction the original request is running inside.

That is exactly what you want when the operation is a core part of the business action. Shared transaction context means the whole unit succeeds or fails together. The problem surfaces when you combine that shared context with unawaited async work.

The Dangerous Pattern

Here is the hook that looks harmless but creates real risk:

// File: src/collections/Orders/hooks/afterChange.ts

import type { CollectionAfterChangeHook } from 'payload'

const afterChange: CollectionAfterChangeHook = async ({ req }) => {
  const result = req.payload.create({
    req,
    collection: 'order-logs',
    data: {
      message: 'Order created',
    },
  })

  // hook continues without waiting
}

The sequence of events this creates is the core of the problem. The async create operation starts. The hook does not wait for it. The request moves forward toward its response. Payload returns a success to the client. Then the async operation fails — and because it was tied to the same transaction via req, the transaction rolls back. The client now holds a success response for data that does not exist in committed form.

This is the warning buried in Payload's documentation:

Since Payload hooks can be async and be written to not await the result, it is possible to have an incorrect success response returned on a request that is rolled back.

It is a dense sentence to read past, but it describes exactly this failure mode.

The Two Safe Patterns

The decision point is one question: should this operation share the fate of the main request?

If yes, it belongs inside the transaction, and you need to both pass req and await the result. If no, it is a detached side effect, and req should not be passed at all.

Pattern A: Transactional and Awaited

// File: src/collections/Orders/hooks/afterChange.ts

import type { CollectionAfterChangeHook } from 'payload'

const afterChange: CollectionAfterChangeHook = async ({ req }) => {
  await req.payload.create({
    req,
    collection: 'order-logs',
    data: {
      message: 'Order created',
    },
  })
}

This preserves the full contract. If the create fails, the transaction rolls back. If it succeeds, you know it is committed before the response goes out.

Pattern B: Detached and Non-Blocking

// File: src/collections/Orders/hooks/afterChange.ts

import type { CollectionAfterChangeHook } from 'payload'

const afterChange: CollectionAfterChangeHook = async ({ req }) => {
  void req.payload.create({
    collection: 'analytics-events',
    data: {
      type: 'order_created',
    },
  })
}

No req. This operation runs on its own transaction, with its own fate. If it fails, that failure is independent — it does not reach back into the original request and undermine the success response.

How This Creeps into Real Projects

Hook code tends to evolve incrementally. You start simple, then add a secondary write, then a notification, then an audit record. At some point it becomes tempting to let some of that work happen in the background to avoid blocking the response.

That is exactly where the dangerous half-state gets introduced. The API reports the main action as successful. One of the secondary operations was still tied to the original transaction. That operation fails. The transaction rolls back. The client believes in a success that never truly committed.

Because the failure only appears when timing and failure conditions align just wrong, happy-path testing never catches it. Everything looks fine until it does not.

FAQ

Does this apply to all Payload hook types, or just afterChange?

It applies to any async hook where you can kick off operations without awaiting them — afterChange, afterOperation, afterRead, and others. The transaction context travels with req regardless of which hook you are in.

What if I want a secondary write to be best-effort but still use the same request context for other reasons?

You cannot safely have both. If you pass req, you opt into the transaction. If you want best-effort behavior, drop req and accept that the operation runs independently with its own transaction.

Is there a way to start a separate transaction explicitly instead of omitting req?

Payload does not currently expose a public API for manually starting a fresh transaction inside a hook. Omitting req is the correct mechanism for detaching an operation from the original request's transactional context.

Will TypeScript catch this mistake?

No. The type signatures for Payload's local API methods accept req as optional. There is no compiler-level warning for the unawaited-with-req combination. It is purely a runtime behavior issue.

How do I handle errors from detached operations if I still care about them?

Wrap the detached call in a standalone try/catch or attach a .catch() handler. Since it is no longer tied to the main request, you are responsible for its error handling independently.

// File: src/collections/Orders/hooks/afterChange.ts

req.payload
  .create({
    collection: 'analytics-events',
    data: { type: 'order_created' },
  })
  .catch((err) => {
    console.error('Analytics write failed:', err)
  })

Conclusion

The Payload async hook transaction trap comes down to one detail: passing req into an operation opts that operation into the request's transaction boundary. Combine that with unawaited async work, and you create a window where a success response goes out before the transaction has actually committed everything it depends on.

The safe habit is straightforward. Await anything that shares the transaction. Detach anything you truly want to run independently by omitting req. That single distinction keeps your hook design consistent and your success responses trustworthy.

Let me know in the comments if you have questions, and subscribe for more practical Payload and Next.js development guides.

Thanks, Matija

The Problem With One Runtime Doing Everything

I was working on a multi-tenant platform built on Payload and Next.js when I noticed something frustrating. Background imports — syncing data from external sources per tenant — were visibly degrading the admin UI and API response times. The jobs were queued correctly, running asynchronously, and technically non-blocking. And yet the web app felt sluggish during heavy import runs.

The root cause was simple. The background jobs and the Next.js web app were running in the same process, on the same container, competing for the same CPU and memory. Non-blocking is not the same thing as isolated. A background job that no longer blocks an HTTP request can still saturate the container it shares with your web server.

That framing changed how I thought about the problem. The question shifted from "should this job run inside Payload?" to "which Payload runtime should own it?"

Web Runtime vs Worker Runtime

Payload's jobs system is designed around role separation. The web runtime handles the admin UI, REST, GraphQL, and fast document operations. The worker runtime executes queued tasks and workflows. Payload explicitly recommends bin scripts for dedicated worker servers because they run in a separate process from the Next.js server, which makes them easier to deploy, monitor, and scale independently.

In practice, the setup is straightforward. You use the same codebase — often the same Docker image — and initialize it differently depending on the role. One container starts the web app. Another starts the job runner, optionally with scheduling enabled. Payload's deployment examples show this directly, with a main app process and separate worker processes assigned to specific queues.

The conceptual shift here is important. This is not about maintaining two separate applications. It is about running one application in two different modes.

Why Compute Separation Is the Real Win

Moving the worker onto separate compute is where the architecture pays off. You can deploy it as another container, another VPS, another ECS service, or another Kubernetes deployment. That gives your web tier predictable latency because it no longer shares resources with long-running jobs.

Your web tier and your worker tier have different performance profiles and different scaling needs. The web tier wants consistent, low-latency responses. The worker tier needs burst CPU, tolerance for longer execution, and more headroom for retries. Forcing one runtime to serve both equally well means neither performs optimally. With the roles split, you can scale each tier horizontally based on what it actually needs.

Payload's queue design supports exactly this. Workers are independent processes. They can be deployed separately, assigned to specific queues, and scaled without touching the web tier.

The Database Is Still the Shared Bottleneck

Separating compute does not eliminate all pressure points. Payload's job system works by queuing work into the database and having workers pick it up and execute it. That shared persistence is what makes independent workers possible — and it also means the database remains the coordination layer for the whole system.

You can isolate CPU-intensive execution away from the web app completely, but if too many jobs write aggressively, lock data frequently, or create excessive transaction churn, the database becomes the limiting factor. Isolating compute is a meaningful gain. Understanding that the database is still shared is the realistic counterpart to that gain.

Concurrency Keys: Safe Scale Across Multiple Workers

In a single-worker setup, job sequencing happens naturally. There is only one active worker loop, so jobs run one after another. As soon as you add more workers, you introduce the possibility that two valid jobs run at the same time against the same resource.

Payload's concurrency model solves this by letting you define a concurrency key per job. When two jobs share the same key, Payload guarantees they run sequentially. The key is stored when the job is queued, and the runner excludes jobs whose key is already being processed. If multiple pending jobs with the same key are picked up in one batch, only the first runs. The rest are released to wait for a later pass.

This is especially relevant for tenant-scoped imports and syncs. Say you have two workers and two queued imports for the same tenant. Without a concurrency key, both workers might process those jobs simultaneously. The jobs are not duplicates — they are different jobs — but they operate on the same tenant data. That is a resource-collision problem. A shared key like import:tenant-123 tells Payload those jobs belong to the same protected lane and must be serialized. Jobs for a different tenant use a different key and can still run in parallel.

The important design decision here is that the concurrency key should be shared by jobs that touch the same resource — not unique per job. Unique keys provide no protection at all.

Tasks vs Workflows: Choosing the Right Model

Payload describes a task as one isolated unit of business logic. A workflow is an ordered group of tasks that can be retried from a specific point of failure rather than from the beginning.

Tasks are a good fit for simple, atomic background work. Workflows become more valuable when a process has multiple dependent stages — fetch, transform, write, finalize — and you care about durable resumption. If a workflow fails on the "write" step, it can resume from there rather than restarting the entire sequence.

For most straightforward background jobs, tasks are sufficient. For anything multi-stage where partial completion has meaningful value, workflows are the right model.

FAQ

Do I need separate infrastructure to separate web and worker roles? You do not need a fundamentally different infrastructure setup. The simplest separation is running two containers from the same Docker image with different start commands — one for the web app and one for the worker. The value scales up from there if you move to separate VPS instances or managed container services.

What happens if I run the worker on the same container as the web app? You will still benefit from the queue architecture and async execution, but the web app and worker will compete for the same CPU, memory, and I/O. Under heavy job load, you can see degraded web app response times even though the jobs are technically non-blocking.

Can I run multiple worker processes against the same queue? Yes, and Payload's queue system is designed to support it. Each worker independently polls the database for jobs. You can run as many worker processes as you need across separate containers or servers.

How does Payload prevent two workers from picking up the same job? Payload uses database-level locking when a worker picks up a job, which prevents other workers from claiming the same job. This is how the queue remains safe across multiple concurrent workers.

When should I use a workflow instead of a task? Use a workflow when the background process has multiple dependent stages and you want durable resumption on failure. If the entire job is a single atomic operation, a task is simpler and sufficient.

Conclusion

The practical takeaway from Payload's jobs system is that it gives you a clean way to separate concerns operationally and scale each concern on its own terms. The web app serves users. Workers handle asynchronous load. The database acts as the shared coordination layer. Concurrency keys protect shared resources when multiple workers run in parallel. And workflows give you a more durable model for complex multi-stage processes.

If you are seeing performance pressure in your Payload app during heavy background work, the architecture is telling you something. The jobs system is built for separation. Using it that way is the intended path.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I ran into this question while setting up a Payload project on ECS. The prodMigrations option looked like the obvious thing to reach for, and the docs did not immediately make clear why that would be a problem at scale. After thinking through how ECS tasks start up and what happens when you have multiple of them, the issue became obvious — and the fix was simpler than I expected.

Schema Migrations Are a Deployment Step, Not a Startup Side Effect

The core confusion is treating schema migrations and application startup as the same concern. They are not.

A schema migration changes the shape of the database — adding columns, renaming fields, modifying indexes, restructuring tables. That work belongs to the deployment lifecycle. Your running application replicas should assume the database is already at the correct schema version when they start. They should not be responsible for establishing it.

Once you hold that framing, the runtime migration pattern becomes obviously wrong in distributed setups. Multiple containers or Pods starting at roughly the same time will each attempt to run migrations against the same database. Even if Payload's migration system handles some failure cases gracefully, you are now depending on startup ordering and shared database state to prevent conflicts. That is not a pattern you want in production.

The Kubernetes and ECS Specifics

In Kubernetes, init containers run per Pod, not once globally for the cluster. If your Deployment scales to three replicas, all three get their own init sequence. A Kubernetes Job, by contrast, runs to completion — it is the right primitive for one-off work like a migration.

In ECS, the same distinction applies. An ECS service is for long-running replicated tasks. A standalone ECS task runs and stops. Migrations belong in the standalone task, not in the startup path of every service task.

The practical rule is:

One migration runner per deployment. All application replicas start only after migrations succeed.

Where that runner lives depends on your platform:

When prodMigrations Actually Makes Sense

Payload includes prodMigrations specifically for cases where build-time database access is not available, or where a single process genuinely owns startup. It is a reasonable option when all of the following are true: you have exactly one application instance, startup-time migration is acceptable, and you are not in a multi-replica race at boot.

Environments where prodMigrations is a reasonable default:

• a single Docker container
• a single VM or long-running Node process
• a tightly controlled internal environment with one startup authority

Environments where it should not be your default:

• Kubernetes Deployments with multiple replicas
• ECS services with multiple tasks
• autoscaled containers
• blue-green or rolling deployments
• any serverless-style cold-start environment (Payload's docs explicitly flag this)

What Payload Recommends

Payload's own guidance reflects this split cleanly. For local development, Drizzle push mode keeps your dev schema in sync while you iterate fast. Once the feature is ready, you generate migration files, commit them, and run them in shared or production environments. Payload also recommends running migrations in CI before the build when DB access is available, and notes that prodMigrations exists mainly as a fallback for when it is not.

The intended split is:

• development — fast schema iteration with push mode
• deployment — explicit migration execution in a controlled step
• runtime — serve traffic, not mutate schema

Implementing the One-Runner Pattern

The implementation varies by platform, but the principle is always the same: run payload migrate once before your replicas scale up, and gate the rollout on migration success.

For a Kubernetes Job running before a Deployment:

# File: k8s/migration-job.yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: payload-migrate
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: your-app-image:latest
          command: ["node", "dist/payload", "migrate"]
          env:
            - name: DATABASE_URI
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: uri
      restartPolicy: Never
  backoffLimit: 0

Run this Job in your CI pipeline before applying the Deployment manifest. The Deployment rollout only proceeds after the Job completes successfully.

For ECS, the equivalent is a run-task call in your deploy pipeline before updating the service:

# File: deploy.sh

aws ecs run-task \
  --cluster your-cluster \
  --task-definition payload-migrate \
  --launch-type FARGATE \
  --network-configuration "..."

# Wait for task to complete, then update the service
aws ecs update-service \
  --cluster your-cluster \
  --service your-service \
  --force-new-deployment

In both cases, the app replicas start already knowing the schema is correct. They do not race to establish it.

FAQ

Can I just use a database lock to prevent concurrent migrations?

Some migration frameworks use advisory locks to prevent concurrent runs. Payload's migration system does offer some protection, but relying on lock behavior in a startup race is operational complexity you do not need. Running migrations in a controlled one-off step is simpler and more explicit.

What if my CI environment does not have database access?

That is the exact case Payload designed prodMigrations for. If you cannot reach the database at build or deploy time, a controlled pre-start migration step is the next best option — either a Kubernetes init Job, an ECS task, or a startup script that runs before replicas come online.

Should I commit Payload migration files to the repository?

Yes. Payload migration files are ordered deploy artifacts with up and down paths. Treat them like release artifacts — generate, review, commit, and execute in a controlled step. Never skip committing them.

Does this apply to local development with Docker Compose?

In a single-developer local environment the risk is low, but the habit is still useful. You can add a migration service to your Compose file that runs and exits before the app service starts, using depends_on with condition: service_completed_successfully.

What happens if a migration fails in the pipeline?

The deploy stops. That is the right behavior. Payload migration files include down paths, so you can roll back if needed. A failed migration surfacing in the deploy pipeline is far better than a failed migration surfacing inside a running production container.

Conclusion

In distributed Payload deployments, migrations belong in a controlled deployment step — not in the startup path of every replica. Running payload migrate once per deployment, before replicas scale up, eliminates startup race conditions and keeps schema readiness as an explicit operational concern. Reserve prodMigrations for single-instance environments where one process genuinely owns startup. For everything else, treat migrations the same way you treat any other release artifact: controlled, sequential, and gated.

Let me know in the comments if you have questions, and subscribe for more practical Payload and Next.js guides.

Thanks, Matija

That's started to change. TanStack Start hit v1 RC in late 2025 with a clear architectural philosophy, a production-capable feature set, and a growing number of developers who are seriously asking whether they still need Next.js. The question is no longer hypothetical.

I've been building with Next.js since the Pages Router era and I've watched the App Router evolve from an interesting bet into the default for serious projects. I've also been paying close attention to TanStack Start since Tanner Linsley's team began pushing it toward stability. This article is my honest take on where each framework wins, where each creates friction, and how to think about the decision if you're choosing right now.

This is not a beginner's guide to either framework. If you need a "what is React Server Components" explainer, this isn't the place. This is for developers and tech leads who already know both names and need a structured way to think about the tradeoff.

What TanStack Start Actually Is (and What It Isn't)

TanStack Start is a full-stack React meta-framework built on top of TanStack Router, using Vite as its build tool and Vinxi as its bundler abstraction. It reached v1 RC on September 22, 2025 — feature-complete and dependency-locked, but not yet fully stable v1.

The important clarification: TanStack Start is not "TanStack Router with a server bolted on." It's a complete rethink of how server rendering should work for teams who want full-stack capabilities without adopting React Server Components as their primary mental model. The server is a capability you reach for explicitly, not the default rendering context for every component.

It supports streaming SSR, full-document rendering, Suspense, and parallel data fetching through isomorphic loaders and server functions. Deployment targets are broad — Vercel, Netlify, Railway, bare Node, Docker, Cloudflare Workers. The Vite foundation means dev server performance that Next.js has historically struggled to match.

What it isn't yet: a framework with the production battle-testing and ecosystem depth of Next.js. More on what that means in practice shortly.

The Philosophical Split: RSC-First vs Client-First with SSR

This is the core difference, and most comparisons either miss it or describe it in terms of syntax rather than architecture. Getting this wrong leads to choosing the wrong framework for reasons that won't hold up six months into a project.

Next.js 16 is RSC-first. Components are server-rendered by default. The App Router treats the server as the primary execution environment and requires you to opt into client behaviour with 'use client'. This model optimises for shipping less JavaScript to the browser and keeping data-fetching co-located with the components that need it. When it works well, it genuinely reduces bundle sizes and simplifies data architecture. When it doesn't, you spend time debugging where a component is running, why a state update isn't triggering what you expected, and why your third-party library broke because it assumed window would be available.

TanStack Start is client-first with explicit server capability. The default mental model is a client-side React application. You reach for server execution explicitly, through createServerFn — a typed RPC-style API where you define server functions with explicit HTTP methods, validators, and middleware. The client-server boundary is something you draw deliberately, not something the framework infers from file structure and directives.

This is a philosophical difference as much as a technical one. Next.js App Router asks you to think in terms of server components and client components as two distinct component types that compose together. TanStack Start asks you to think in terms of a client application that makes typed calls to server endpoints. If your team has been writing React for years and finds the RSC mental model genuinely friction-heavy rather than just unfamiliar, TanStack Start's approach will feel more natural.

Neither model is objectively better. They optimise for different things. RSC-first is better when you want server rendering to be pervasive and low-ceremony. Client-first with explicit server functions is better when you want predictability, transparency, and explicit control over where code runs.

Routing and Data Fetching Compared

Both frameworks use file-based routing. The similarity mostly ends there.

TanStack Router (the routing layer inside TanStack Start) enforces type safety at the routing layer with compile-time param validation. Route params, search params, and loader data are all fully typed — not inferred at runtime, but validated at build time. If a route expects an id param and you pass something that doesn't match the schema, you get a type error before deployment. This is a genuine differentiator for large codebases where route-level bugs are expensive to catch.

Next.js App Router uses file-based conventions with page.tsx, layout.tsx, loading.tsx, and the rest of its directory-based routing model. It's expressive and familiar, but it carries implicit behaviours — particularly around caching — that have been the source of significant developer frustration. Revalidation bugs, unexpected staleness, and the general opacity of the caching model have been recurring pain points since App Router became stable. Next.js 16 has improved this, but the underlying complexity is structural.

On data fetching: TanStack Start uses isomorphic loaders that run on the server during SSR and in the browser after hydration. They integrate naturally with TanStack Query, which means you get the full cache and background refetch behaviour of React Query without a separate data layer. createServerFn handles mutations and server-side logic with explicit type safety — you specify the HTTP method, define a validator (Zod or otherwise), and get full type inference on both ends of the call.

Next.js Server Actions use a 'use server' directive and default to POST for mutations. They're simpler to set up for straightforward cases but less explicit about what's happening at the HTTP level. For teams that want to understand and control their network layer, TanStack Start's approach is easier to reason about. For teams that want to move fast without thinking about HTTP semantics, Server Actions are genuinely less friction.

If you're working through Next.js serialisation issues with complex data types, the patterns in this guide on server-to-client serialisation in Next.js illustrate exactly the kind of complexity the TanStack data model is designed to avoid.

Production Readiness — What "RC" Actually Means for Your Project

TanStack Start being in RC status deserves an honest assessment rather than a dismissal or a handwave.

RC in the context of TanStack Start means: the API is locked, dependencies are pinned, the feature set is complete, and the team considers it stable for production use. It does not mean it has years of production battle-testing behind it, a rich ecosystem of third-party integrations, or a large community of Stack Overflow answers to lean on when something breaks.

In practice, this matters in specific ways. The deployment story is solid — deploying anywhere Node runs works correctly, and the Vite foundation means builds are fast and predictable. Performance on the server rendering path is competitive with Next.js. One team's migration from Next.js to TanStack Start (Inngest) reported 83% faster local dev times, which is a meaningful productivity signal even if it's a single data point.

Where ecosystem thinness shows up: third-party library compatibility, auth library support depth, and integration with CMS platforms. The Next.js App Router architectural patterns that are well-documented and community-tested simply don't have equivalents in the TanStack Start ecosystem yet.

The honest summary: RC means you can ship production systems with it today, but you'll hit underdocumented edges, you'll have fewer community resources when you do, and you'll be making architectural decisions without the benefit of collective scar tissue from thousands of production deployments. For a team with strong senior engineers who are comfortable navigating undocumented territory, this is manageable. For a team that relies on ecosystem depth and community answers, it's a real risk.

Where Next.js 16 Still Wins

Next.js 16, released October 21 2025, shipped Turbopack as the stable default bundler — a genuine improvement to dev performance that partly closes the gap TanStack Start's Vite foundation had. React Compiler support is now stable, and React 19.2 integration is deep. The App Router is mature enough that the worst early roughness has been sanded down.

More importantly: the ecosystem is vast. Auth libraries, CMS integrations, monitoring tools, and deployment platforms have all invested in Next.js specifically. Authentication patterns are well-established, internationalisation is well-understood, and the number of senior developers who have Next.js production experience means hiring and team scaling is easier.

For content-heavy systems, Next.js still has a structural advantage. Its RSC model keeps pages lean by default, which matters for SEO-critical public websites where JavaScript payload directly affects core web vitals. The Pages Router is still supported for teams that need a migration path without abandoning the framework entirely.

If your project involves a headless CMS, Next.js wins clearly at the integration layer. The ecosystem has converged on Next.js as the default target — Payload CMS, Sanity, Contentful, and the rest all treat Next.js as the primary integration surface.

Where TanStack Start Wins

For teams building applications rather than content sites — dashboards, SaaS products, internal tools — the TanStack Start philosophy aligns more naturally with how complex application state actually works.

Type safety at the routing layer is the most underrated advantage. When route params, search params, and loader data are all compile-time typed, a category of runtime bugs simply stops existing. For large applications with complex navigation and deep linking, this is meaningful correctness that Next.js App Router doesn't offer at the same level.

Explicit server boundaries reduce the debugging overhead of the "is this component running on the server or the client?" question that App Router creates. When you call a server function, you know you're calling a server function. There's no directive to misplace and no implicit serialisation to debug. The mental model is closer to how developers who grew up with REST APIs think about client-server communication.

Deployment flexibility matters for teams that want to avoid optimising for Vercel's infrastructure. TanStack Start builds produce standard Node output that runs correctly anywhere — no platform-specific edge cases, no implicit optimisations that only work on one provider.

And Vite's dev server speed is still faster than Turbopack in most real-world configurations. For teams doing active development on large codebases, the day-to-day productivity difference is real.

Choose TanStack Start If... / Choose Next.js 16 If...

Choose TanStack Start if:

• You're building an application (dashboard, SaaS, internal tool) rather than a content site
• Your team finds RSC mental model creates more confusion than it solves
• Type-safe routing is a priority and you want compile-time guarantees on params and search state
• You're deploying to non-Vercel infrastructure and want to avoid platform-specific behaviour
• Your team has strong senior engineers comfortable with thinner ecosystem coverage
• You're coming from a React SPA background and want SSR without re-learning the rendering model from scratch

Choose Next.js 16 if:

• You're building a content-heavy public site where SEO and core web vitals are critical
• You're integrating with a headless CMS — particularly Payload, Sanity, or Contentful
• Your team needs to hire developers with existing framework experience
• You need auth, i18n, and monitoring integrations with minimal custom configuration
• You need the confidence that comes from years of production case studies and community answers
• Your project requires the full depth of the React 19 ecosystem working together with server rendering

The decision is rarely about which framework is technically superior in the abstract. It's about which framework's constraints align with your team's strengths and your project's requirements.

What This Means If You're Using Payload CMS

This section matters specifically for anyone building Payload-backed systems, because the compatibility picture is not symmetric.

Payload CMS is architecturally native to Next.js. From v3.0 onwards, Payload runs inside a Next.js application — the same Next.js project hosts both the admin panel and the public frontend. The official withPayload plugin handles all the build wiring, and Turbopack compatibility was formally added in Next.js 16 (PR #14456). For teams building Payload-powered websites and applications, this is a deep, well-tested integration that removes an entire class of configuration problems.

TanStack Start can work alongside Payload CMS, but not in the same native way. Because TanStack Start uses Vite and Vinxi as its build system, you hit bundler conflicts when trying to run Payload in the same project — Vite's module resolution handles some file types differently from the webpack-based build Payload expects. The workable approach is a monorepo setup where Payload runs in a separate Next.js application and TanStack Start consumes it as an API. This is architecturally reasonable but it's a meaningfully higher integration overhead than the native approach.

For the kind of systems described in how to structure Payload CMS collections for maintainability — structured knowledge bases, customer-facing sites with semantic search, AI-powered interfaces — the native Next.js integration is a real advantage. The best headless CMS guide for Next.js in 2026 covers this in more detail for teams still evaluating the CMS layer.

If Payload is your CMS, Next.js is still the correct framework choice until TanStack Start's Vite compatibility story matures.

The Honest Summary

TanStack Start is the most interesting architectural challenge to Next.js dominance that exists today. It makes a coherent argument — explicit server boundaries, type-safe routing, Vite performance, deploy-anywhere flexibility — and the argument is good enough that teams should take it seriously rather than dismissing it as an early experiment.

Next.js 16 remains the safer choice for most production systems, particularly content-heavy sites, CMS-backed applications, and teams that need ecosystem depth to move fast. The RSC model has matured significantly, Turbopack is now genuinely fast, and the collective knowledge base that comes from years of widespread production use is not something to underestimate.

The framework worth watching: TanStack Start will close the ecosystem gap over the next twelve to eighteen months. If type-safe routing and explicit server architecture resonate with how your team thinks, building familiarity with it now makes sense. If you're shipping a production system today and need confidence at every layer, Next.js 16 is still the right bet.

If you're making this architectural decision for a system that needs to handle real operational complexity — structured data, AI interfaces, workflow automation — and you want a senior perspective on getting the architecture right before writing code, feel free to reach out.

Thanks, Matija

I took on my first WordPress-to-Payload migration for a client running a content-heavy site with seven years of posts, several ACF field groups, and a media library approaching 4,000 files. I assumed the hard part would be the infrastructure — setting up the Next.js app, configuring Payload collections, deploying to production. The infrastructure went fine. The hard part was the content. WordPress stores almost everything as unstructured HTML in a single wp_posts table, and getting that into Payload's typed, structured format takes real transformation work. This guide documents everything I learned, including the failure modes that cost me two days.

What You're Actually Migrating

Before writing a single line of the ETL script, you need a complete inventory of what exists in WordPress and what needs to happen to each type.

Posts and pages live in wp_posts with post_type values of post and page. The post_content column contains raw HTML — sometimes clean <p> tags, sometimes Gutenberg block comment markup, sometimes shortcode output from plugins that no longer exist. The post_status column tells you what's published (publish), drafted (draft), or in the trash (trash). You only want publish.

Custom post types are also rows in wp_posts with custom post_type values registered by themes or plugins. If you've been running ACF, your custom types will have corresponding meta rows in wp_postmeta keyed by ACF field keys.

ACF fields are stored as individual rows in wp_postmeta. Each field becomes a meta_key/meta_value pair. Simple fields (text, number, image ID) produce a single row. Repeaters and flexible content layouts serialize their structure into a PHP-style array that gets stored as a string — more on that in the failure points section.

The media library consists of wp_posts rows with post_type = 'attachment'. Each row has a corresponding _wp_attached_file meta entry in wp_postmeta containing the relative path within wp-content/uploads/. The actual files live on disk or in an S3 bucket depending on your hosting setup.

Users are in wp_users with roles stored in wp_usermeta. If you're migrating a multi-author site, you'll need a Payload users collection and a mapping between WordPress user IDs and Payload user document IDs.

Taxonomies — categories and tags — live in wp_terms, wp_term_taxonomy, and wp_term_relationships. Each post's taxonomy assignments are rows in wp_term_relationships.

Menus are stored in wp_posts as nav_menu_item post types with menu structure in wp_postmeta. Unless you're building a dynamic menu system in Payload, you'll likely hard-code these in your Next.js layout rather than migrating them.

wp_options is the global key-value store for WordPress settings, plugin configuration, and serialized PHP data structures. Do not blindly copy it. Extract only the specific values you need (site URL, blog name) and treat everything else as WordPress-internal.

Here's how each type maps to Payload:

Content Model Mapping: WordPress Post Types → Payload Collections

The content model is where you make the decisions that everything else depends on. Get this wrong and you'll be rewriting migration scripts halfway through.

A standard WordPress blog post maps straightforwardly to a Payload collection. Here's a complete TypeScript collection config for a posts collection that mirrors what WordPress stores:

// File: src/collections/Posts.ts
import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
    defaultColumns: ['title', 'status', 'publishedAt'],
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
      index: true,
    },
    {
      name: 'wordpressId',
      type: 'number',
      index: true,
      admin: {
        description: 'Original WordPress post ID — used for relationship fixups and delta imports',
      },
    },
    {
      name: 'content',
      type: 'richText',
    },
    {
      name: 'excerpt',
      type: 'textarea',
    },
    {
      name: 'featuredImage',
      type: 'upload',
      relationTo: 'media',
    },
    {
      name: 'categories',
      type: 'relationship',
      relationTo: 'categories',
      hasMany: true,
    },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users',
    },
    {
      name: 'status',
      type: 'select',
      options: ['draft', 'published'],
      defaultValue: 'draft',
    },
    {
      name: 'publishedAt',
      type: 'date',
    },
    {
      name: 'seoTitle',
      type: 'text',
    },
    {
      name: 'seoDescription',
      type: 'textarea',
    },
  ],
}

The wordpressId field is critical. Every document you create in Payload during migration should carry the original WordPress ID. You'll use it for relationship fixups (linking posts to their categories after both are imported), delta imports (querying WordPress for posts modified after your initial ETL run), and debugging when something goes wrong mid-migration.

Mapping ACF field groups to Payload fields is where the real design work lives. Simple ACF fields map directly:

// File: src/collections/Projects.ts — ACF field group mapping examples
import type { CollectionConfig } from 'payload'

export const Projects: CollectionConfig = {
  slug: 'projects',
  fields: [
    // ACF text field → Payload text field
    { name: 'clientName', type: 'text' },

    // ACF image field → Payload upload field
    { name: 'heroImage', type: 'upload', relationTo: 'media' },

    // ACF repeater field → Payload array field
    {
      name: 'testimonials',
      type: 'array',
      fields: [
        { name: 'quote', type: 'textarea' },
        { name: 'author', type: 'text' },
        { name: 'role', type: 'text' },
      ],
    },

    // ACF flexible content → Payload blocks field
    {
      name: 'sections',
      type: 'blocks',
      blocks: [
        {
          slug: 'textBlock',
          fields: [
            { name: 'heading', type: 'text' },
            { name: 'body', type: 'richText' },
          ],
        },
        {
          slug: 'imageGrid',
          fields: [
            {
              name: 'images',
              type: 'array',
              fields: [{ name: 'image', type: 'upload', relationTo: 'media' }],
            },
          ],
        },
        {
          slug: 'callToAction',
          fields: [
            { name: 'heading', type: 'text' },
            { name: 'buttonText', type: 'text' },
            { name: 'buttonUrl', type: 'text' },
          ],
        },
      ],
    },
  ],
}

The ACF-to-Payload mapping follows a reliable pattern: simple scalar fields become Payload scalar fields, ACF repeater becomes a Payload array with the same sub-fields, and ACF flexible_content with its layout definitions becomes a Payload blocks field with one block per layout. The Payload wp-to-payload repository shows this side-by-side for a sample site, which is useful as a reference alongside this mapping.

The ETL Script: Extract, Transform, Load

With collections defined, you can write the migration script. I'll walk through extraction from the WordPress REST API, transformation to Payload's format, and loading via the Local API. For large sites (10,000+ posts), prefer a SQL dump as your source — it's faster and doesn't require keeping WordPress live throughout the migration. For most content sites, the REST API is simpler to work with.

First, set up the Payload client for standalone script usage. The Payload CMS SDK: CLI Toolkit article covers the shared authenticated client pattern in detail — the Local API initialization below follows that same approach:

// File: scripts/migrate-posts.ts
import { getPayload } from 'payload'
import config from '@payload-config'
import { convertHTMLToLexical, editorConfigFactory } from '@payloadcms/richtext-lexical'
import { JSDOM } from 'jsdom'

const WP_BASE_URL = process.env.WP_BASE_URL // e.g. https://old-site.com
const WP_PER_PAGE = 100

async function fetchWordPressPosts(page: number) {
  const url = `${WP_BASE_URL}/wp-json/wp/v2/posts?per_page=${WP_PER_PAGE}&page=${page}&_embed=1&status=publish`
  const res = await fetch(url)
  if (!res.ok) throw new Error(`WP REST error: ${res.status}`)
  const totalPages = Number(res.headers.get('X-WP-TotalPages') ?? 1)
  const posts = await res.json()
  return { posts, totalPages }
}

The REST API returns posts with content.rendered as an HTML string, featured_media as a media attachment ID, categories as an array of term IDs, and acf as an object of field values when the ACF REST API extension is active. The _embed=1 parameter inlines the featured media object so you can get the source URL without a second request.

Before you can convert content.rendered to Lexical, you need to upload all images referenced in that HTML to Payload first. The convertHTMLToLexical function from @payloadcms/richtext-lexical does not auto-upload images — it will silently drop any <img> tags that aren't annotated with the correct Payload data attributes. Handle media upload in a separate pass before converting content, then annotate the HTML.

// File: scripts/upload-media.ts
import { getPayload } from 'payload'
import config from '@payload-config'
import path from 'path'
import fs from 'fs'
import { pipeline } from 'stream/promises'
import { createWriteStream } from 'fs'
import os from 'os'

// Map from WordPress attachment ID → Payload media document ID
const mediaIdMap = new Map<number, string>()

async function uploadWordPressMedia(
  payload: Awaited<ReturnType<typeof getPayload>>,
  wpMediaId: number,
  sourceUrl: string,
): Promise<string | null> {
  // Check if already uploaded
  const existing = await payload.find({
    collection: 'media',
    where: { wordpressId: { equals: wpMediaId } },
    limit: 1,
  })
  if (existing.docs.length > 0) {
    return existing.docs[0].id as string
  }

  // Download to temp file
  const tmpPath = path.join(os.tmpdir(), `wp-media-${wpMediaId}-${Date.now()}`)
  const res = await fetch(sourceUrl)
  if (!res.ok || !res.body) return null
  await pipeline(res.body as any, createWriteStream(tmpPath))

  const filename = path.basename(new URL(sourceUrl).pathname)

  try {
    const doc = await payload.create({
      collection: 'media',
      data: {
        alt: filename,
        wordpressId: wpMediaId,
      },
      filePath: tmpPath,
    })
    mediaIdMap.set(wpMediaId, doc.id as string)
    return doc.id as string
  } finally {
    fs.unlinkSync(tmpPath)
  }
}

[!WARNING] Your media collection needs a wordpressId field (type number, indexed) — the same pattern as the posts collection. This lets you skip already-uploaded files on re-runs and perform relationship fixups.

With media uploaded and mediaIdMap populated, annotate image tags in the HTML before converting to Lexical:

// File: scripts/migrate-posts.ts (continued)

function annotateImagesInHtml(
  html: string,
  mediaIdMap: Map<number, string>,
  wpMediaByUrl: Map<string, number>,
): string {
  const dom = new JSDOM(html)
  const document = dom.window.document

  document.querySelectorAll('img').forEach((img) => {
    const src = img.getAttribute('src') ?? ''
    // Match the WordPress media ID from the URL if we have it
    const wpId = wpMediaByUrl.get(src)
    const payloadId = wpId ? mediaIdMap.get(wpId) : undefined

    if (payloadId) {
      img.setAttribute('data-lexical-upload-id', payloadId)
      img.setAttribute('data-lexical-upload-relation-to', 'media')
    }
  })

  return dom.serialize()
}

async function convertToLexical(html: string) {
  const editorConfig = await editorConfigFactory({})
  const { editorState } = await convertHTMLToLexical({
    html,
    editorConfig,
    JSDOM,
  })
  return editorState
}

Now tie extraction, transformation, and loading together:

// File: scripts/migrate-posts.ts (continued)

async function migratePosts() {
  const payload = await getPayload({ config })

  // First, build a map of WP category term ID → Payload category document ID
  // (assumes categories collection is already migrated)
  const categoryIdMap = await buildCategoryIdMap(payload)

  let page = 1
  let totalPages = 1

  while (page <= totalPages) {
    const { posts, totalPages: tp } = await fetchWordPressPosts(page)
    totalPages = tp

    for (const wpPost of posts) {
      // Skip if already migrated
      const existing = await payload.find({
        collection: 'posts',
        where: { wordpressId: { equals: wpPost.id } },
        limit: 1,
      })
      if (existing.docs.length > 0) {
        console.log(`Skipping WP post ${wpPost.id} — already migrated`)
        continue
      }

      // Annotate image HTML before Lexical conversion
      const annotatedHtml = annotateImagesInHtml(
        wpPost.content.rendered,
        mediaIdMap,
        wpMediaByUrl, // Map<url, wpMediaId> built during media upload pass
      )
      const lexicalContent = await convertToLexical(annotatedHtml)

      // Map category IDs
      const payloadCategoryIds = (wpPost.categories as number[])
        .map((id) => categoryIdMap.get(id))
        .filter(Boolean) as string[]

      // Map featured image
      const featuredImageId = wpPost.featured_media
        ? mediaIdMap.get(wpPost.featured_media)
        : undefined

      await payload.create({
        collection: 'posts',
        data: {
          title: wpPost.title.rendered,
          slug: wpPost.slug,
          wordpressId: wpPost.id,
          content: lexicalContent,
          excerpt: wpPost.excerpt.rendered.replace(/<[^>]+>/g, '').trim(),
          featuredImage: featuredImageId ?? null,
          categories: payloadCategoryIds,
          status: 'published',
          publishedAt: wpPost.date,
        },
      })

      console.log(`Migrated: ${wpPost.title.rendered} (WP ID: ${wpPost.id})`)
    }

    page++
  }

  await payload.destroy()
  console.log('Migration complete.')
}

migratePosts().catch(console.error)

Run this with tsx scripts/migrate-posts.ts — the CLI toolkit article covers the tsx + tsconfig.paths.json setup required to resolve @payload-config in standalone scripts.

For sites with thousands of posts, processing them in sequence is slow. The bulk data import with Payload Queues article covers the queue-based pattern for large-volume imports — the same approach applies here, with each WP post ID dispatched as a job task.

Media Migration: Re-uploading the WordPress Media Library

The script above uploads media on-demand during post migration. For a complete media library migration — including files not directly embedded in post content — you need a dedicated media pass first.

The WordPress REST API exposes all attachments at /wp-json/wp/v2/media. Each record includes a source_url for the full-size file and a media_details object with the available image sizes:

// File: scripts/migrate-media.ts
import { getPayload } from 'payload'
import config from '@payload-config'

async function fetchAllWpMedia(baseUrl: string) {
  const allMedia: any[] = []
  let page = 1
  let totalPages = 1

  while (page <= totalPages) {
    const res = await fetch(
      `${baseUrl}/wp-json/wp/v2/media?per_page=100&page=${page}`,
    )
    totalPages = Number(res.headers.get('X-WP-TotalPages') ?? 1)
    const batch = await res.json()
    allMedia.push(...batch)
    page++
  }

  return allMedia
}

async function migrateMediaLibrary() {
  const payload = await getPayload({ config })
  const wpMedia = await fetchAllWpMedia(process.env.WP_BASE_URL!)

  for (const item of wpMedia) {
    const existing = await payload.find({
      collection: 'media',
      where: { wordpressId: { equals: item.id } },
      limit: 1,
    })
    if (existing.docs.length > 0) continue

    // Download to temp, then create in Payload
    const payloadId = await uploadWordPressMedia(payload, item.id, item.source_url)
    if (payloadId) {
      console.log(`Uploaded: ${item.source_url} → Payload ID ${payloadId}`)
    }
  }

  await payload.destroy()
}

migrateMediaLibrary().catch(console.error)

[!NOTE] Payload won't replicate WordPress's media URL structure (e.g., /wp-content/uploads/2023/04/image.jpg). Uploaded files get Payload's own path structure. Accept this early and plan your redirect rules to cover /wp-content/uploads/ paths pointing to Payload's new media URLs. This is also why the wordpressId field on media documents is essential — it lets you build a mapping table for any legacy media URLs embedded in non-Lexical content.

Shortcodes and HTML That Won't Survive Conversion

content.rendered from the WordPress REST API is the post-processed HTML — shortcodes are already evaluated by the time the API returns them. This sounds helpful, until you look at what the shortcodes actually rendered. Plugin-generated tables. Slider markup. Contact form placeholders. Payment button HTML. None of it maps to Lexical nodes, and convertHTMLToLexical will silently discard markup it can't parse.

The realistic approach depends on your content's HTML complexity:

The staged migration approach stores the original HTML in a custom field and renders it via dangerouslySetInnerHTML on the front end, giving you a working site on day one while you migrate content to structured Lexical incrementally:

// File: src/collections/Posts.ts — staged migration variant
{
  name: 'legacyHtml',
  type: 'textarea',
  admin: {
    description: 'Raw HTML from WordPress — render via dangerouslySetInnerHTML until migrated to richText',
    condition: (data) => Boolean(data.legacyHtml),
  },
},
{
  name: 'contentMigrated',
  type: 'checkbox',
  defaultValue: false,
  admin: {
    description: 'Set to true once legacyHtml has been converted to the richText field',
  },
},

In your Next.js page component, check contentMigrated to decide which field to render. Once a post is fully converted, the legacyHtml field can be cleared.

The community package @teagantb/payload-wordpress-migration provides WordPress XML import, REST API import, and block-to-Lexical conversion via an Admin UI. Worth evaluating for your specific content mix before building custom shortcode parsers.

[!WARNING] Gutenberg block comment delimiters (<!-- wp:paragraph -->) appear verbatim in post_content when queried directly from the database or via the REST API's content.raw field. Always use content.rendered from the REST API, which returns the evaluated HTML output. If you're working from a SQL dump, run content through WordPress's apply_filters('the_content', $post_content) before exporting — or use the REST API as your extraction source.

SEO and URL Preservation: 301 Redirect Strategy

WordPress supports several permalink structures. The most common ones you'll encounter and their Next.js redirect equivalents:

Date-based (/2024/03/my-post/) — WordPress's default for many sites:

// File: next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async redirects() {
    return [
      // Date-based: /2024/03/my-post/ → /blog/my-post
      {
        source: '/:year(\\d{4})/:month(\\d{2})/:slug',
        destination: '/blog/:slug',
        permanent: true,
      },
      // Category-prefixed: /news/my-post/ → /blog/my-post
      {
        source: '/news/:slug',
        destination: '/blog/:slug',
        permanent: true,
      },
      // WordPress media library paths → Payload media URLs
      // If you can build a static mapping, use individual redirects
      // For large libraries, handle in Next.js middleware instead
      {
        source: '/wp-content/uploads/:path*',
        destination: '/api/media-redirect/:path*',
        permanent: false, // Keep as 302 until all URLs are verified
      },
    ]
  },
}

export default nextConfig

The :year(\\d{4}) and :month(\\d{2}) syntax uses path-to-regexp regex constraints — Next.js supports this natively. The captured :slug parameter carries through to the destination.

For category-prefixed URLs, you'll need one redirect entry per category unless all categories follow the same pattern. If you have dozens of categories, generate the redirects array programmatically by querying your Payload categories collection and building the array at build time.

WordPress pagination (/page/2/, /page/3/) and archive URLs (/category/news/, /tag/typescript/, /author/matija/) don't exist in Payload by default. Redirect them to the closest equivalent pages you've built in your Next.js app, or to the homepage if no equivalent exists:

// File: next.config.ts (additional redirect entries)
{
  source: '/page/:pageNum',
  destination: '/blog',
  permanent: true,
},
{
  source: '/category/:category',
  destination: '/blog',
  permanent: true,
},
{
  source: '/tag/:tag',
  destination: '/blog',
  permanent: true,
},
{
  source: '/author/:author',
  destination: '/',
  permanent: true,
},
// WordPress feed URLs
{
  source: '/feed',
  destination: '/rss.xml',
  permanent: true,
},

[!TIP] Before going live, run your full WordPress URL list through a redirect checker. Export all published post URLs from WordPress (Screaming Frog or a SQL query on wp_posts where post_status = 'publish') and verify every one returns a 301 in your Payload + Next.js setup. Missing redirects on high-authority URLs are the fastest way to lose search rankings during cutover.

Content Freeze and Cutover

The content freeze is the moment you stop WordPress from accepting new content and begin the final delta import. Done correctly, you lose no content and minimize the DNS switch window.

Step 1 — Freeze WordPress publishing. Put WordPress in maintenance mode or disable editing for all users except your migration account. The simplest approach is a plugin like WP Maintenance Mode, or adding define('DISALLOW_FILE_EDIT', true) and removing editor roles temporarily.

Step 2 — Run the full ETL. Execute your migration scripts in order: media first, then flat collections (categories, tags, users), then posts and pages (which reference the flat collections via relationship fields), then any CPTs. Log every WordPress ID you migrate successfully.

Step 3 — Relationship fixup pass. Query every Payload document and verify that relationship fields (featuredImage, categories, author) are populated. The wordpressId field on each document is your key — query WordPress for the relationship IDs, look them up in Payload by wordpressId, and patch any gaps with payload.update().

Step 4 — Delta import. The initial ETL might take hours on a large site. By the time it finishes, WordPress may have received new content (before the freeze) or you may have missed a status filter. Query the WordPress REST API for posts modified after your ETL start timestamp:

// File: scripts/delta-import.ts
const etlStartTime = '2026-03-01T00:00:00' // ISO timestamp of initial ETL run

const res = await fetch(
  `${WP_BASE_URL}/wp-json/wp/v2/posts?modified_after=${etlStartTime}&per_page=100&status=publish`,
)
const newOrModifiedPosts = await res.json()
// Re-run the same create/update logic, using wordpressId to detect existing docs

Step 5 — Smoke test. Verify a sample of 20–30 posts across different content types. Check that rich text renders correctly, images load, relationships are populated, and slugs match what you've configured in Next.js routes.

Step 6 — DNS switch. Point your domain to the new Payload + Next.js deployment. Keep the WordPress instance accessible (ideally on a subdomain) for at least 48 hours after cutover. convertHTMLToLexical downloads images from the original URL during migration — if any media uploads failed and you need to re-run them, you'll need the old site reachable.

Step 7 — Monitor Search Console. Watch for crawl errors in Google Search Console over the first two weeks. Missing redirects show up as 404s on URLs that previously had inbound links. Fix them as they appear.

For infrastructure considerations during and after cutover, the Payload CMS + Next.js self-hosted deployment guide covers the production setup.

Common Failure Points

Serialized PHP in wp_options. WordPress plugins store configuration as PHP-serialized strings. If you extract wp_options directly from the database, you'll encounter values like a:3:{i:0;s:4:"text";}. PHP serialization is not JSON — never attempt to parse these as JSON. Extract only the specific option keys you need by name (e.g., blogname, blogdescription, siteurl) and ignore the rest.

Orphaned wp_postmeta rows. Deleting posts in WordPress leaves wp_postmeta rows behind. If your SQL query joins wp_postmeta to wp_posts, you may encounter meta rows with no matching post. Filter on wp_posts.post_status = 'publish' and use an INNER JOIN to exclude orphaned meta.

ACF repeater and flexible content serialization. When ACF stores complex field types, it writes the field values as individual rows in wp_postmeta with numbered key suffixes (e.g., testimonials_0_quote, testimonials_0_author, testimonials_1_quote). There's also a testimonials key containing the count. The REST API's acf object deserializes these into a proper array automatically. If you're working from a SQL dump, you'll need to reconstruct the array from the numbered rows yourself.

WooCommerce data. If your WordPress site runs WooCommerce, treat the product, order, and customer data as a completely separate migration scope. WooCommerce stores its data across wp_posts, wp_postmeta, and several custom tables (woocommerce_order_items, woocommerce_order_itemmeta, etc.). Migrating WooCommerce to Payload's ecommerce architecture is a distinct engagement from migrating editorial content.

Page builder markup. If the WordPress site used Elementor, Divi, Beaver Builder, or WPBakery, the post_content field contains proprietary shortcode or JSON syntax specific to that builder. content.rendered from the REST API outputs the rendered HTML, which is usable but often heavily nested and will not convert cleanly to Lexical blocks. Use the staged migration approach for these posts.

_wp_attachment_metadata and custom image sizes. WordPress generates multiple image sizes for every upload (thumbnail, medium, large, custom). Payload's media handling works differently — you define image sizes in your collection config and Payload generates them on upload. You don't need to migrate the cropped variants, only the original files. Let Payload regenerate sizes from the originals.

FAQ

Do I need to keep WordPress running during the migration?

For the media upload pass, yes — the ETL script downloads media files directly from their WordPress URLs. If you're working from a SQL dump rather than the REST API, you still need file access for the binary uploads. The simplest approach is keeping WordPress on a subdomain (e.g., legacy.yourdomain.com) until the migration is confirmed complete.

How do I handle WordPress multisite?

Multisite adds a site ID prefix to all tables (wp_2_posts, wp_2_postmeta). The migration logic is identical — you just parameterize the table prefix per site and run the ETL once per site into separate Payload collections or a multi-tenant Payload setup.

What happens to WordPress user passwords?

WordPress hashes passwords using a custom PHPass implementation that's incompatible with standard bcrypt. You cannot migrate WordPress password hashes into Payload directly. The cleanest approach: migrate user records without passwords, then trigger a password reset email for all users on launch day.

Can I run the ETL script incrementally without a full re-run?

Yes — the wordpressId field and the modified_after REST API parameter are what make this possible. On each script run, check for an existing Payload document with the matching wordpressId before creating. Use payload.update() for documents that already exist. This means you can stop and resume the ETL at any point without duplicating data.

How long should I keep the 301 redirects in next.config.ts?

Permanently. There's no cost to keeping redirect rules in next.config.ts, and removing them risks breaking inbound links from external sites that haven't updated their references. Treat legacy WordPress URL redirects as permanent infrastructure.

Doing This at Scale or With a Tight SEO Deadline?

This guide covers the full technical path for a WordPress-to-Payload migration: content modeling, ETL scripting, media re-upload, HTML-to-Lexical conversion, shortcode handling, URL redirects, and cutover sequencing. Running this against a large site — heavy ACF usage, thousands of posts, complex permalink structures, SEO-critical URLs — adds significant scoping, QA, and testing work on top of what's covered here.

My Payload CMS migration service is exactly this work. If you want a principal-led migration with a realistic timeline and a clean SEO handoff, that's where to start.

Conclusion

WordPress-to-Payload is a full stack shift, and the content layer is where most migrations get stuck. The wp_posts HTML blob problem, the convertHTMLToLexical image annotation requirement, the ACF field mapping decisions, the redirect coverage — each of these is a real source of project delay if you hit it unprepared. The approach in this guide — media-first migration, wordpressId mapping on every document, staged HTML handling for complex content, and a freeze + delta-import cutover — gives you a repeatable process that you can stop, resume, and verify at each step.

If you have questions about specific parts of your migration, drop them in the comments below.

Thanks, Matija

The problem isn't a lack of information. It's that every "best headless CMS for Next.js" article in existence is either written by a vendor, curated by a vendor, or structured as a feature matrix that completely misses the actual decision. Feature tables tell you what a CMS can do. They don't tell you what you'll regret.

I've built production systems on Strapi, Sanity, and Payload across clients in Germany, the UK, and the US. This article is a decision framework based on what actually drives those regrets — and the five axes that determine whether a CMS fits your specific situation, not someone else's.

If you've already decided on Payload and want a deep technical evaluation, that article exists here. This one is for the decision that comes before that.

Why Every CMS Comparison Article Gets This Wrong

The standard format is: list six CMSes, compare features, give each a star rating, declare a winner. It's easy to produce and useless to use, because it treats CMS selection as a tooling decision when it's actually an infrastructure commitment with a three-year tail.

The feature that matters in week one (visual editing, or TypeScript-native schema) is rarely the feature that causes problems in month eighteen. What causes problems in month eighteen is your data ownership model when the vendor changes pricing, your upgrade path when the framework releases a breaking version, your ops burden when your self-hosted instance needs a security patch at 2am.

None of that appears in a feature table.

So before looking at any specific CMS, the real question is which of the five decision axes are hard constraints for your situation. The CMSes follow from the constraints, not the other way around.

The Five Axes That Actually Determine the Right CMS

1. Self-Hosted vs SaaS: The Ownership Decision

This is the most important axis and the one most comparison articles treat as a checkbox. It's not a checkbox. It's a commitment with financial, operational, and legal implications that compounds over time.

The SaaS model — Sanity, Contentful, Storyblok — gives you managed infrastructure, global CDN, automatic backups, and zero server administration. You pay a monthly fee and the vendor handles everything that would otherwise be your problem. The tradeoff is that your content lives in their system, their pricing model applies as you scale, and their roadmap decisions affect your product. The cost cliff is real: agencies that put clients on Contentful or Sanity at the free or entry tier consistently report the same pattern — growth is fine until it isn't, and the jump to the next pricing tier is not a gentle step. Contentful's Lite plan sits at $300/month; above that is custom enterprise pricing. Sanity's per-seat Growth plan compounds as the content team grows.

The self-hosted model — Payload, Strapi — means your content lives in your own Postgres instance, your own infrastructure, and you control the data completely. GDPR compliance becomes a constraint you manage rather than a promise you take on faith. Cost predictability at scale is real because you're paying for compute, not for content volume. The tradeoff is that you own the operational problem: database backups, version upgrades, security patches, Postgres management.

The regret pattern on the SaaS side is cost surprises and vendor pricing changes. The regret pattern on the self-hosted side is operational overhead — teams that choose Strapi routinely underestimate how resource-intensive it runs, and discover gaps like missing native 2FA and painful version transitions only after they're committed.

The decision rule here is clean: if data residency, GDPR compliance at the infrastructure level, or cost predictability at scale are hard requirements, start with self-hosted. If zero infrastructure ownership and fast onboarding matter more than those constraints, SaaS is the faster path.

2. Code-First vs GUI-First: DX vs Editor UX

The second axis determines who controls the content model and who lives in the CMS daily.

Code-first means your content schema is defined in code — TypeScript files, version-controlled, reviewed in PRs, deployed like application code. Payload is the extreme end of this: you define collections in TypeScript, your types are generated automatically, and the admin UI is a reflection of your code rather than a source of truth for schema. Strapi v5 sits in similar territory, with TypeScript schema definitions and a more code-first philosophy than its v4 predecessor. The developer experience of code-first is excellent. The editor experience for non-technical content teams can be unfamiliar.

GUI-first means content editors can modify content types, add fields, and reshape the data model through a visual interface without touching code. Contentful and Storyblok lean this way — marketing teams can adapt the content model without filing a ticket. The tradeoff is that schema changes made through a GUI are harder to version, review, and audit.

Sanity sits in the middle in practice. Schemas are defined in code, which gives you developer control and version history. But the Studio UI is genuinely polished — it's the one CMS where non-technical editors consistently adapt without much training.

One data point worth naming directly: Strapi v5.5 has had a difficult period. Developers in active community threads describe months of build issues, broken TypeScript compilation for custom plugins, and documentation that didn't keep up with the release. Some teams have switched to Directus or Payload mid-project as a result. This isn't fatal for Strapi — v5 is the current major and the TypeScript improvements are real — but it's a risk to weigh honestly if your team will be building custom plugins on an aggressive timeline.

The decision rule: if your entire team is developers and the content operation is small, code-first DX wins. If a non-technical marketing team manages content daily and the editor experience is a hard requirement, GUI-first or Sanity's balanced middle is the safer choice.

3. Next.js App Router Compatibility: More Than "Next.js Support"

Every comparison article says each CMS "supports Next.js." That's nearly useless information in 2026. The App Router has fundamentally changed how Next.js applications are structured — React Server Components, streaming, Draft Mode, revalidateTag for ISR, and the shift away from getServerSideProps. CMS support varies significantly at this level, and the difference between native App Router integration and a generic REST API fetch in a server component is not just ergonomic. It's performance and architectural clarity.

Payload has the strongest App Router integration by design. Because Payload installs directly into your Next.js application rather than running as a separate service, server components can query the database through Payload's local API without an HTTP round-trip. No authentication layer to cross. No serialisation boundary. Draft Mode is handled inside the same application. This is architecturally different from every other option on this list.

Sanity has explicit App Router support through the next-sanity package, with documented revalidateTag integration and a functioning Draft Mode pattern via the Live Content API. This is mature and well-maintained.

Storyblok has first-class App Router support with an official guide tested against Next.js 15.4. Draft Mode integration with the Visual Editor is documented and maintained. For teams that need Storyblok's visual editing with App Router, the path is clear.

Contentful and Strapi work through their REST or GraphQL APIs, which are compatible with the App Router but don't offer SDK-level optimisations for server components, streaming, or App Router-specific patterns. They're adequate but generic.

If you're building for App Router from the start — which you should be for any new project in 2026 — this axis matters more than it appears in most comparisons.

4. AI Readiness at the Data-Model Level

This is the axis that no current comparison article addresses properly, and it's increasingly the one that determines whether your CMS choice ages well.

The question isn't which CMS has "AI features." It's which CMS is architecturally ready for RAG pipelines, MCP server exposure, and event-driven AI automation. If you're building a content system in 2026 and not thinking about how AI will interact with it in the next two years, you're planning a migration later.

AI-ready content architecture requires four things at the data-model level. First, structured JSON fields rather than HTML blobs — AI systems need to consume specific fields reliably, not parse presentation-coupled markup. Second, event-driven change propagation so that when content changes, AI workflows (embedding sync, translation, validation) trigger automatically. Third, native or easily integrated vector index support for semantic search and RAG. Fourth, access-control-aware retrieval so that in user-scoped RAG scenarios, the LLM only sees content the authenticated user is permitted to access.

Here is how the main options score against those requirements:

Payload is the only CMS on this list that positions itself as built for RAG from the ground up. AI Auto-Embedding is a native feature that adds vector indexes directly into your existing Postgres database, handles chunking and embedding sync automatically as content changes, and applies user-level access control to RAG queries. There is an official Payload MCP Server for exposing your content to AI assistants. For teams building AI-native applications, this is the only option with a first-party RAG story at the infrastructure level.

Sanity has a comparable architecture story: the Embeddings Index handles semantic search natively, Sanity Functions enable event-driven automation where content changes can trigger LLM processing with results written back to draft fields, and an official MCP server exists. Sanity's AI architecture guidance — AI writes to drafts, humans publish — is well-documented. The difference from Payload is that Sanity's data lives in their managed infrastructure, which intersects with the data ownership axis.

Contentful has an official MCP server and a webhook framework that can drive external vector sync. AI Actions and AI Suggestions handle content operations. But there is no native RAG story comparable to Payload or Sanity — you would integrate an external vector database and manage synchronisation yourself through webhooks.

Storyblok includes AI Search and AI credits in their pricing tiers, and community MCP tooling exists. No first-party vector index or RAG-native architecture. External integration is possible but not guided.

Strapi has webhooks and lifecycle hooks that can feed content into external AI systems, and a community MCP server. No native AI-readiness features in the core product. The most manual path of the five if AI integration is a priority.

If you know AI workflows will be part of your architecture in the next 18 months, treat this axis as a leading indicator. Picking a CMS that requires a full content model migration to enable RAG later is expensive in ways that don't show up in the initial evaluation.

5. Upgrade Path Stability

The most-ignored axis, and the one that generates the most post-mortem regret.

This applies differently depending on your hosting model. For self-hosted CMSes, the risk is major version transitions — API changes, plugin incompatibilities, documentation gaps that don't keep pace with releases. The Strapi v4 to v5 situation is a concrete example: v4 is now in maintenance mode with security updates guaranteed only until April 2026, v5 introduced breaking changes across plugin APIs, and teams with significant custom plugin investment have reported TypeScript compilation failures and weeks spent on what should have been routine upgrades.

For SaaS CMSes, the risk is different — pricing model changes, feature deprecations, and acquisition-driven roadmap uncertainty. Payload's acquisition by Figma in June 2025 raised genuine concerns in some developer communities about long-term OSS continuity, even though the weekly release cadence has continued unchanged (v3.78.0 shipped February 27, 2026) and the official position is that self-hosting remains fully supported. The concern is real regardless of whether it proves founded, because it creates evaluation friction for new adopters.

The honest framing: stability risk lives on both sides of the hosted/self-hosted divide. What to actually check before committing is the release history (are major versions introducing breaking changes at high frequency?), the migration documentation quality (is upgrading well-documented or does it require reading GitHub issues?), and whether the vendor has a track record of deprecating features teams depend on without adequate runway.

The Decision Matrix

Based on the five axes, here is the framework in plain terms.

Choose Payload if your team is all developers, TypeScript is native to your stack, data ownership and GDPR compliance are hard requirements, you're building AI workflows into the application, and you want the tightest possible App Router integration. Accept that the ecosystem is smaller than Strapi or WordPress, the documentation is still catching up with the release pace, and you will build more integrations yourself than you would with a more mature platform.

Choose Sanity if you need a polished editor experience for non-technical content teams, your content operation is editorial-heavy, you want structured content at scale with a mature ecosystem, and SaaS hosting is acceptable. Sanity's AI architecture story is strong and the App Router integration is solid. Accept per-seat pricing that compounds as your team grows, and content that lives in Sanity's managed infrastructure rather than yours.

Choose Contentful if you are in an enterprise context with existing vendor relationships, compliance SLAs and 24/7 support are contractual requirements, and budget is not the primary constraint. Accept that you are paying for enterprise assurance, the API model is generic with no App Router-level optimisations, and the jump from Lite to enterprise pricing is a significant step.

Choose Storyblok if visual editing is a non-negotiable requirement — your marketing team needs to build and edit pages through a visual interface, not a form-based editor. The App Router and Draft Mode integration is first-class, and the pricing model is reasonable at small to medium scale. Accept no native RAG or AI-readiness story in the core product.

Choose Strapi if open-source licensing is required, your team wants a GUI schema builder without going fully code-first, and SaaS pricing is a hard blocker. Strapi v5 is the current major with meaningful TypeScript improvements. Accept the v5 upgrade risk if you have significant custom plugin investment, and plan to build your AI integration layer manually.

Choose WordPress headless if you are migrating an existing WordPress site with a large content corpus, your editorial team will not change tools, or your plugin dependencies are deep enough that replicating them in a headless CMS costs more than keeping WordPress as the backend. WordPress with WPGraphQL 2.x and MCP adapters is a real 2026 stack. Accept the developer experience overhead of building a Next.js frontend on WPGraphQL.

TCO: What You Actually Pay Over 36 Months

Plan pricing is the least useful number in a CMS evaluation. Here is what the cost picture actually looks like across three scenarios.

Solo founder or very small team with a simple content model: SaaS options are genuinely free or very low cost at this scale — Sanity's free tier, Storyblok Starter, Contentful Free. Payload or Strapi self-hosted on a $20/month VPS is comparable in spend. The real difference is time: SaaS takes minutes to set up, self-hosted takes a day and requires ongoing maintenance. At this scale, TCO favours SaaS unless data ownership is a hard constraint.

10-person company with a content team of three to five non-technical editors: Sanity Growth at $15/seat/month means $45–75/month for the content team alone before any usage overages. Contentful Lite at $300/month is a flat fee but a meaningful commitment for a small business. Storyblok Growth at $99/month is competitive. Payload self-hosted on managed Postgres plus a small VPS runs $30–60/month in infrastructure, but requires DevOps time for setup, upgrades, and incident response — budget roughly two to four hours per month ongoing. Over 36 months, the SaaS options typically cost more in absolute spend; the self-hosted option costs more in engineering time. Which is more expensive for your team depends entirely on your engineering rate.

Growth-stage company with compliance requirements and multi-market needs: Contentful Premium and Sanity Enterprise are both contact-sales territory. Budget $1,000–5,000+ per month depending on volume and seats. Self-hosted Payload at this scale requires a proper infrastructure setup — managed Postgres, automated backups, monitoring, staging environments — which runs $200–500/month in infrastructure plus meaningful DevOps overhead. The compliance advantage of self-hosting (your data, your jurisdiction, your audit trail) is real at this scale and often worth the operational cost when weighed against enterprise SaaS pricing.

The number nobody models is migration cost. If you choose wrong and need to change CMSes 18 months in, you are looking at a full content model re-mapping exercise, editor retraining, and frontend refactoring. That cost — typically two to four weeks of senior engineering time — should weigh in the initial evaluation, not only the monthly subscription.

Putting the Framework to Work

There is no universally best headless CMS for Next.js. There is the right one for your specific constraint set, and that is determined by working through the five axes in order: ownership model first, then editor UX, then App Router depth, then AI readiness, then upgrade stability.

The matrix above gives you the shortcut. But the honest path is to identify which axes are hard constraints for your project — the ones where the wrong choice causes a migration later — and let those drive the decision. Feature tables don't surface those constraints. This framework tries to.

If you have worked through this and Payload is the answer for your situation, the deeper evaluation of Payload's architecture, growth trajectory, and specific gotchas is in this article. If you are comparing Payload directly against Sanity, that comparison covers the architectural trade-offs in detail. For the vendor lock-in question specifically, this piece breaks down what switching actually costs. And if you've already chosen Payload and need to decide where to host it, the Payload CMS hosting guide walks through Vercel, Cloudflare, VPS, and managed container options with real cost comparisons.

If you have questions about how these axes apply to your specific project — the constraint set that doesn't fit neatly into a matrix — drop a comment below. And if you found this useful, subscribe for more.

Thanks, Matija

I recently worked with a company operating across several markets — multiple brands, each with its own website, its own CMS, its own hosting setup, and its own publishing workflow. One market ran on WordPress. Another on a different platform. A third on something nobody quite remembered choosing. On paper, the setup looked reasonable. In practice, every website update had to be coordinated separately, brand consistency drifted over time, and adding a new market meant standing up an entirely new system from scratch. The question they came to me with was not really a technical question. It was an operational one: how do we stop managing five versions of the same problem?

That situation is more common than it sounds. And the answer, more often than not, involves rethinking the underlying architecture rather than rebuilding each website one by one.

Multi-Site Management Should Not Require Multiple Systems

Every growing company eventually manages more than one web presence. That is normal. What creates problems is not the number of websites — it is what happens to the systems behind them.

When websites are built separately, they tend to accumulate separately too. Different CMS platforms, different hosting providers, different design systems, different vendor contracts, different technical setups. Over time, the stack multiplies because each new website or market makes sense as a standalone decision at the moment it is launched.

The fragmentation is not always visible from the outside. Brand websites can look well-maintained while the infrastructure behind them is a patchwork of disconnected systems. But internally, the cost of that fragmentation is constant.

What Fragmentation Looks Like Inside a Growing Organization

If your organization manages websites across multiple brands, subsidiaries, or geographic markets, some of these will sound familiar.

Every update gets repeated. A global navigation change, a new privacy policy, a design adjustment — it has to be applied separately on each website, by different people, on different platforms, sometimes in different languages. Teams spend time on repetition instead of meaningful work.

Updates fall out of sync. Because changes are applied manually across systems, they drift. One website reflects the new brand guidelines. Another still shows the old ones. A third has an intermediate version that nobody intended to ship. The gap between what the business decided and what visitors actually see grows quietly over time.

Governance becomes unclear. When each website has its own system and its own team managing it, accountability becomes fragmented too. Who owns the standard? Who approves content before it goes live? Who notices when something is wrong? These questions are hard to answer cleanly when the infrastructure is different for every brand.

Technical debt compounds. Each system has its own update cycle, its own security patches, its own hosting contract. Maintaining five platforms means maintaining five separate cost and risk profiles. When something breaks, it is harder to diagnose and fix because there is no shared foundation.

New market launches are slow. Standing up a new brand website from scratch — finding a vendor, configuring a new CMS, migrating content, setting up workflows — takes months. With a shared foundation, that same process can take weeks.

The Better Model: One Foundation, Controlled Independence

A multi-tenant CMS architecture changes the operating model. Instead of running separate systems for each brand or market, you run one system that can power multiple websites simultaneously. Each website still has its own identity, its own content, and its own team managing it. But the underlying infrastructure is shared.

The key distinction decision makers often miss is this: multi-tenancy is not about forcing all brands into one giant generic website. It is about sharing the infrastructure while keeping the surface layer distinct.

Think of it the way a well-run group operates at the corporate level. Shared finance, legal, and HR systems. Separate brand strategies. The structure is shared. The identity is independent.

That is the same principle applied to web infrastructure.

What Stays Shared, What Stays Separate

The practical question is always: what actually gets shared, and what stays brand-specific?

The result is that teams operating within a brand still feel full ownership of their website. They manage their content, control their publishing workflow, and see only their brand in the admin interface. What they do not see — and do not need to think about — is the shared infrastructure running underneath.

When This Architecture Makes Business Sense

Multi-tenant website architecture is a strong fit in specific situations. It is worth evaluating seriously if your organization matches any of these.

Multiple subsidiaries under one parent company. You have distinct brand identities that need to remain independent, but they share enough structural similarity that rebuilding the same foundation five times does not make sense.

Regional or market-specific websites with local content needs. The core website structure is the same across markets, but content, language, and local pages need to be managed separately by regional teams.

Growth through acquisition. You have absorbed brands with their own websites and now manage a fragmented mix of platforms. Consolidation onto a shared foundation reduces ongoing maintenance without requiring each brand to sacrifice its identity.

New market expansion. You are planning to launch into new geographies and want to do so without building a new system each time. A shared foundation makes each launch faster and cheaper.

Inconsistency across brands. Brand standards are drifting across websites and there is no clean mechanism to enforce them centrally. A shared component and template layer gives central teams more control without removing local autonomy.

When It Does Not Make Sense

Not every multi-website situation benefits from consolidation. It is worth being clear about this.

If your brands have fundamentally different structures — one is a product catalogue, another is a service brochure, another is a community platform — the technical divergence may outweigh the benefit of a shared foundation.

If your organization has only one or two websites and no near-term expansion plans, the overhead of setting up a multi-tenant architecture adds complexity without a clear return.

If your brands need to remain completely separate for regulatory or competitive reasons, shared infrastructure may not be appropriate even with logical data isolation.

The honest answer is that this architecture is a strong fit when there is real structural overlap across brands and a genuine operational cost to maintaining them separately. Where that overlap is thin, simpler solutions usually serve better.

Why Payload CMS Is a Strong Fit for This Model

Payload CMS handles multi-tenancy natively through its official multi-tenant plugin. This matters practically because it means the architecture does not require stitching together multiple systems or maintaining custom isolation logic across the codebase.

Each brand or market operates as a separate tenant within one Payload instance. Content, users, and permissions are scoped per tenant automatically. A regional editor logs in and sees only their brand's content. A super admin can access and manage all brands from one place.

The plugin is maintained officially and kept current with Payload's release cycle, which means the isolation logic does not drift as the system is updated. For organizations managing multiple brands over a multi-year horizon, that kind of maintained stability matters more than it might seem at first.

Because Payload runs natively inside a Next.js application, the frontend and the CMS share the same codebase, the same TypeScript types, and the same deployment. That tight coupling reduces the architectural surface area that needs to be maintained — fewer moving parts, fewer vendor dependencies, fewer integration points that can break.

Questions to Ask Before Consolidating Your Website Stack

If you are evaluating whether multi-tenant CMS architecture is the right move for your organization, these are the questions worth working through first.

How many websites are we managing today, and how many are we likely to manage in three years? The answer changes the calculus significantly.

How much duplication exists across our current websites? Are we rebuilding the same structures, the same templates, the same content types on each one?

Where are updates getting stuck? Are changes delayed because they need to be applied separately across systems? Is that causing visible inconsistency?

What should be standardized across brands, and what must remain brand-specific? The clearer this line is, the more straightforward the architecture becomes.

Is our current vendor and platform mix sustainable at scale? If adding one more brand means adding one more system, that cost compounds quickly.

Are we scaling a system or just duplicating one? This is the question that usually clarifies the decision.

Frequently Asked Questions

Does multi-tenancy mean all our brands will look the same?

No. Visual identity, content, domain, and publishing workflows all remain separate per brand. What is shared is the infrastructure underneath — the CMS, the hosting setup, the component foundation, and the maintenance cycle. Brands still look, feel, and operate independently for both visitors and editors.

How does user access work? Will editors from one brand see content from another?

In a properly configured multi-tenant setup, editors are scoped to their brand. They log into the same admin interface but see only the content, media, and settings belonging to their tenant. Super admins can access everything. Brand-level editors cannot.

We have brands running on different CMS platforms. Is migration a realistic option?

It depends on the scale and structure of the content. Migrations are common and manageable, but they require realistic planning. For most organizations, the right approach is a phased consolidation — starting with the brand that has the cleanest structure — rather than migrating everything at once.

Can we keep brand-specific domains?

Yes. Each brand retains its own domain. The multi-tenant architecture routes each domain to the correct brand content within the shared system. From a visitor's perspective, nothing changes.

How much faster is launching a new market with this architecture in place?

The time saving is significant but depends on content complexity. For structurally similar markets, the difference between launching a new brand on a shared foundation versus standing up an entirely new system can be measured in weeks versus months. The shared foundation handles the setup; the brand team focuses on content.

Closing

For multi-brand companies, the issue is rarely the number of websites. It is the number of disconnected systems behind them.

Fragmentation is the real cost — in time, in consistency, in governance, in the speed at which the business can move. Multi-tenant architecture does not eliminate brand independence. It gives organizations one shared foundation from which multiple brands can operate cleanly, without duplicating the infrastructure every time the portfolio grows.

If you are managing multiple brand or subsidiary websites and want to understand whether this model applies to your situation, the starting point is a clear picture of where your current stack is creating friction. That is the conversation worth having before any architecture decision is made.

If you found this useful or have questions about your specific situation, let me know in the comments. And if you are exploring this for your organization, the discovery call is the right place to start.

Thanks, Matija

A CMS migration has five phases: content audit, content model redesign, data transformation, SEO and URL preservation, and cutover. Most migrations fail in phase two — not phase five. This guide walks through every phase in the order you actually need to execute them, with the specific decisions that determine whether you end up with a cleaner system or just the same mess in a new container. If your team is handling the migration in-house, this is the checklist. If you're evaluating whether to hand it off, the Payload CMS migration service page covers what that engagement looks like.

I've run enough CMS migrations to know exactly where they break. The pattern is consistent: a company treats migration as a data transfer problem, copies their existing content structure into the new system, and ships a site that inherits every piece of technical debt from the old one. Six months later they're asking why the new CMS feels exactly as painful as the old one.

The real work of a migration isn't moving data. It's making the architecture decisions that the original CMS setup never got right. That happens in phase two, before a single ETL script runs. If you skip it or rush it, the rest of the checklist doesn't matter.

Before You Start: Is Migration the Right Move?

Migration is a meaningful investment of both capital and engineering time. It's worth doing when your current system has become a genuine bottleneck — not because someone on the team read about a new CMS and got excited.

Signals that migration is the right move:

Plugin debt that eats engineering capacity. If your team spends more time patching security vulnerabilities and fighting plugin conflicts than building features, the hidden cost of staying is higher than the migration cost.

SaaS API billing that scales faster than your traffic. Contentful and similar platforms charge per API record, per space, per environment. When those bills start forcing architectural compromises, you've crossed the threshold.

AI integration that your current CMS can't support. If you're trying to build custom AI agents, RAG pipelines, or semantic search and the CMS's closed ecosystem makes every integration fragile, you're fighting the wrong battle.

Multi-tenant or multi-market requirements. Managing multiple brands on a system that charges per site or per space doesn't scale. A unified backend with proper access control changes the economics entirely.

Signals that you should wait:

No internal developers. Code-first CMSes require engineering involvement. If your team doesn't have that capacity, a migration will fail at the maintenance phase even if the initial build goes well.

A genuinely simple site. Five static pages that change quarterly don't need a full migration. The ROI isn't there.

Budget constraints below the minimum threshold. A migration done cheaply enough to cut corners on SEO preservation and data integrity will cost more to fix than a proper migration would have cost.

The Two Migration Strategies: Big-Bang vs. Incremental

Every other checklist in this space skips this decision. It's the most important one you'll make before any technical work begins.

Big-bang migration means you build the new system in parallel, run a full cutover on a fixed date, and redirect traffic all at once. The old system goes dark. The new system goes live. This is simpler to manage and creates a clean break, but it concentrates all the risk into a single go-live moment. If something breaks at cutover, everything is broken.

Incremental migration means you run both systems simultaneously and route traffic progressively — one section, one content type, or one route at a time. You use nginx, middleware, or a reverse proxy to direct specific URLs to the new system while the rest still serve from the old one. The risk is distributed across multiple smaller cutovers. No single moment of maximum exposure.

Most companies with active publishing, e-commerce, or customer-facing systems should default to incremental. The parallel running period is longer and the routing logic adds complexity, but losing a week of revenue to a botched cutover costs more than the extra engineering time.

For incremental migrations, the checklist phases below still apply — they just repeat for each section of the site rather than running once for everything.

Phase 1: Content Audit and Inventory

Before a line of code is written, you need to know exactly what you're migrating. This sounds obvious. It almost never gets done properly.

The deliverable is a content inventory: every content type, every field, every asset, and every piece of content that has ever been published. Most teams discover during this phase that their CMS holds years of accumulated content that nobody has looked at since it was published. Blog posts from 2014. Campaign landing pages for offers that ended three years ago. Product pages for items that are no longer sold.

The harder task in this phase isn't cataloging what exists — it's deciding what shouldn't migrate at all.

ROT analysis (Redundant, Obsolete, Trivial) is the right framework here. For each content type, you're asking: is this content still accurate, is it still relevant to the business, and does it have any meaningful traffic or conversion value? Content that fails all three criteria stays behind. The new system should start cleaner than the old one, not inherit its full archive indiscriminately.

A practical approach: export your full URL list, cross-reference it against Google Search Console for trailing 90-day click data, and flag anything with zero traffic and no strategic reason to exist. You'll typically eliminate 20–40% of the content inventory before migration even begins. Every page you don't migrate is a page you don't have to transform, test, redirect, and maintain.

Phase 1 checklist:

• Full content type inventory documented
• Field-by-field catalog for each content type
• Asset inventory (images, PDFs, video embeds, file attachments)
• Internal link map (pages that reference other pages)
• ROT analysis complete — "do not migrate" list finalized
• Content that remains tagged by priority (must-have at launch vs. can migrate post-launch)

Phase 2: Content Model Redesign

This is the phase that determines whether the migration was worth doing. It's also the phase most teams underinvest in.

Your current CMS has a content model — even if nobody consciously designed it. WordPress stores content as post types with custom fields and metadata scattered across a dozen tables. Contentful has content types with reference fields pointing to other content types. Sanity has schemas with Portable Text blocks that have evolved through years of editorial decisions. The common thread is that all of them reflect the decisions (and compromises) made by whoever set up the CMS, often years ago, often without a clear architectural intent.

Migrating that model directly into a new system preserves every mistake.

The right approach is to treat the new system's content model as a greenfield design that happens to need to accommodate your existing content. Start with what the business actually needs the content to do — not what the current CMS happens to store. Define your collections, your fields, your relationship structure, and your access control model as if you were starting fresh. Then map your existing content to that new structure.

For teams moving to Payload CMS, this means designing typed TypeScript collections that reflect your actual content relationships. A product page isn't just a post with a custom field — it's a typed collection with specific fields, specific relationships to other collections (categories, variants, related products), and specific access control rules. The admin interface your editors use every day is generated directly from that TypeScript definition.

The hard work in this phase is handling the cases where old content doesn't map cleanly to the new model. WordPress often stores rich content as HTML blobs in the post content field — years of Gutenberg and Classic Editor output that needs to be parsed and converted to structured blocks. Contentful's Rich Text JSON format has a specific structure that needs to be converted to Payload's Lexical format. Sanity's Portable Text blocks map reasonably well to Lexical but still require a transformation pass.

Every edge case you identify in this phase — malformed HTML, inconsistent field usage, broken internal links, embedded shortcodes — needs a transformation rule before the scripting phase begins. Discovering them in phase three, mid-import, is expensive.

Phase 2 checklist:

• New content model designed independently of old CMS structure
• Collections and globals defined in the target system
• Field types selected for each piece of content (rich text, relationship, array, block, etc.)
• Relationship mapping complete (which collections reference which)
• Access control model defined
• Content type mapping table: old content type → new collection, field by field
• Edge cases and exceptions documented with transformation rules
• Rich text conversion strategy defined (HTML/portable text/rich text JSON → target format)

For platform-specific guidance on the content model mapping step, the WordPress to Payload migration guide, Contentful to Payload migration guide, Sanity to Payload migration guide, and Strapi to Payload migration guide cover the specifics for each source platform.

Phase 3: Data Transformation and Scripting

With the content model defined and every edge case documented, the technical extraction and import work can begin.

The approach is ETL: extract data from the source system, transform it to match the new schema, and load it into the target. For most CMS migrations, this means custom Node.js scripts that hit your source system's API (REST or GraphQL), apply transformation logic for each content type, and use the target system's API to create records in the correct structure.

For Payload CMS, the Local API is the right tool for the import phase. It bypasses HTTP overhead, runs in the same Node.js process, and gives you full access to hooks and validation — which means your imported content goes through the same data integrity checks as content created through the admin UI.

A few practical notes on running the import reliably:

Start with a subset. Run your first import script against 5–10 records of each content type, verify the output in the admin UI, and fix transformation issues before processing the full dataset. The edge cases you documented in phase two will show up immediately and are far cheaper to fix on 10 records than on 10,000.

Handle relationships in the right order. Collections that other collections reference need to exist before the referencing records are created. Map your dependency graph before you write the import scripts and run collection imports in the correct sequence.

Log everything. Every record that fails transformation, every field that falls back to a default, every relationship that can't be resolved — all of it needs a log entry. You'll need this log to verify completeness and to catch data integrity issues before cutover.

Assets are usually the most time-consuming part. Images, PDFs, and other media files need to be downloaded from the source, uploaded to your new storage layer, and their references updated in the transformed content. For large asset libraries this step dominates the total import time.

Phase 3 checklist:

• Extraction scripts written for each content type
• Transformation logic covers all edge cases documented in Phase 2
• Import scripts written using target system's API/local API
• Dependency order for collections mapped and respected
• Subset test import run and verified
• Asset migration script written and tested
• Full import run in staging environment
• Import logs reviewed — all failures resolved or explicitly accepted
• Record count reconciliation: source count vs. target count per content type

Phase 4: SEO and URL Preservation

The biggest risk in any CMS migration is losing search rankings. It's also the most predictable risk — which means it's entirely preventable with the right preparation.

The core requirement is 1:1 URL mapping. Every URL that existed in the old system and had any meaningful traffic needs to either exist in the new system at the same path or have a 301 redirect to its new location. A 301 redirect tells search engines that the content has permanently moved, passes the ranking equity of the old URL to the new one, and ensures that any bookmarks or external links don't result in 404 errors.

The mapping process starts from the content inventory you built in Phase 1. For every URL in the old system that you're migrating, document the old URL and the new URL it will resolve to. For content you've decided not to migrate, decide whether to redirect to the nearest relevant page or let it return 404 — the latter is appropriate for content that was never indexed or has no ranking value.

The implementation depends on your infrastructure. For an incremental migration, you're adding redirects progressively as each section cuts over — routing specific URL patterns to the new system while others still hit the old one. For a big-bang migration, you're implementing the full redirect map at cutover. In both cases, the redirect map needs to be tested in staging before it touches production.

Beyond redirects, metadata preservation matters. Page titles, meta descriptions, canonical tags, and schema.org structured data should all be preserved or improved during migration. Most migrations that cause an SEO dip do so because content was migrated without its metadata — the content arrived, but the signals that told Google what it was didn't come with it.

For incremental migrations, there's an additional concern: duplicate content during the parallel running period. While both systems are live, you need to ensure that content served from the old system has canonical tags pointing to the final URL in the new system, or that the old system's pages are noindexed during the transition. Running two versions of the same content without a canonical signal is the fastest way to lose ranking equity you've spent years building.

Phase 4 checklist:

• Full 301 redirect map built from content inventory
• Old URLs with no migration path — decision documented (redirect or 404)
• Redirect map tested in staging (no redirect chains, no loops)
• Page titles and meta descriptions confirmed present in new system
• Canonical tags configured correctly
• Schema.org structured data preserved or improved
• XML sitemap updated for new URL structure
• For incremental migrations: canonical/noindex strategy for parallel period defined

Phase 5: Staging, Cutover, and Stabilization

Everything in phases one through four has been preparation. Phase five is execution — and the goal is to make it boring.

The parallel running period is the safety net. Before any production traffic changes, the new system runs in staging with a full copy of the migrated content, accessible to your team for verification. This is not user acceptance testing of the UI — it's data integrity verification. You're checking that every record migrated correctly, that every relationship resolved correctly, that every redirect works, and that every piece of metadata arrived intact.

The content freeze is the mechanism that makes cutover clean. At a fixed point before the final import — typically 48–72 hours before DNS change — the old system goes into read-only mode. No new content is published, no existing content is edited. This ensures that the final delta import (the pass that catches any content created after the initial bulk import) doesn't miss anything.

For incremental migrations, "cutover" is a series of smaller events rather than a single moment. Each section of the site cuts over independently — you update the routing configuration to send a specific URL pattern to the new system, verify it's working correctly, and move on to the next section. The content freeze applies per-section rather than site-wide.

The go-live sequence for a big-bang cutover:

1. Final delta import from source system
2. Verify record counts and spot-check content in staging
3. DNS change (TTL should have been reduced to 5 minutes 48 hours prior)
4. Verify redirects are firing correctly on production
5. Check Google Search Console for crawl errors within 24 hours
6. Monitor Core Web Vitals and ranking positions for 2–4 weeks post-launch

The stabilization period is 2–4 weeks of active monitoring. Most ranking fluctuations after a well-executed migration are temporary — Google re-crawls, reassesses, and typically restores positions within a few weeks. What you're watching for is anything that shouldn't fluctuate: a sudden drop in a previously stable high-traffic page, crawl errors that indicate broken redirects, or 404s that indicate URLs that weren't in your redirect map.

Phase 5 checklist:

• Staging environment fully populated with migrated content
• Data integrity verification complete (record counts, spot checks, relationship checks)
• All team members have verified their content sections in staging
• DNS TTL reduced 48 hours before cutover
• Content freeze date communicated to editorial team
• Final delta import scripted and tested
• Go-live sequence documented and rehearsed
• Monitoring setup: GSC crawl errors, Core Web Vitals, ranking tracking
• Rollback plan documented (how to revert DNS if critical issues emerge within first hour)

The Full CMS Migration Checklist

For reference, the complete checklist across all five phases:

Phase 1 — Content Audit

• Content type inventory documented
• Field-by-field catalog complete
• Asset inventory complete
• Internal link map built
• ROT analysis complete — do-not-migrate list finalized
• Remaining content tagged by launch priority

Phase 2 — Content Model Redesign

• New content model designed for target system
• Collections and globals defined
• Field types selected
• Relationship mapping complete
• Access control model defined
• Content type mapping table built (old → new, field by field)
• Edge cases documented with transformation rules
• Rich text conversion strategy defined

Phase 3 — Data Transformation

• Extraction scripts written per content type
• Transformation logic covers all documented edge cases
• Import scripts using target API/local API
• Collection dependency order respected
• Subset test import run and verified
• Asset migration script tested
• Full staging import complete
• Import logs reviewed
• Record count reconciliation complete

Phase 4 — SEO Preservation

• 301 redirect map built
• Unmigrated URLs — redirect or 404 decision documented
• Redirect map tested in staging
• Metadata confirmed in new system
• Canonical tags configured
• Structured data preserved
• XML sitemap updated
• Parallel period canonical/noindex strategy (incremental only)

Phase 5 — Cutover

• Staging data integrity verification complete
• DNS TTL reduced 48h prior
• Content freeze communicated
• Delta import scripted and tested
• Go-live sequence documented
• Monitoring configured
• Rollback plan documented

FAQ

How long does a CMS migration take?

For a mid-sized site (500–5,000 pages, standard content model), plan for 8–12 weeks end-to-end. The content audit and content model redesign in phases one and two typically take longer than teams expect — two to three weeks for a thorough job. The scripting and import phase depends heavily on how clean the source data is. Enterprise migrations with custom integrations, multi-tenant architecture, or high-volume datasets run 12–20 weeks. Timelines compress when phase two is rushed and expand when edge cases surface mid-import.

Will we lose SEO rankings when we migrate?

Not if phases four and five are executed correctly. A well-implemented 301 redirect map passes ranking equity to new URLs. Improving page speed and structured data during the migration often produces an SEO lift in the weeks after launch. The risk is concentrated in two areas: missing URLs in your redirect map (which produce 404s) and metadata that didn't migrate with the content (which weakens the ranking signals for individual pages). Both are preventable with the verification steps in the checklist.

Can we migrate without rebuilding the frontend?

Yes. If you already have a modern React or Next.js frontend consuming your old CMS via API, you can swap the data source from the old CMS to Payload without touching the frontend. The work is purely on the backend: new Payload installation, content model design, data import, and API endpoint mapping. Most teams choose to rebuild the frontend simultaneously to take advantage of Payload's Next.js integration, but it's not a requirement.

What's the hardest part of migrating from WordPress?

WordPress stores rich content as HTML in the post content field — years of Gutenberg blocks, Classic Editor output, shortcodes, and inline styles that need to be parsed and converted to structured blocks. The transformation scripts for this step are the most complex part of a WordPress migration. Custom post types with ACF fields are usually straightforward; the post content blob is where the edge cases multiply. See the WordPress to Payload migration guide for the specifics.

When does incremental migration make more sense than big-bang?

When any of the following apply: the site has active e-commerce or transactional flows that can't have downtime, the editorial team publishes daily and can't freeze content for a week, the existing system has integrations with CRMs or marketing tools that need to stay live during transition, or the team has limited QA capacity and needs to verify each section before moving to the next. The routing complexity of incremental migration is a known cost. The risk of a botched big-bang cutover on a live business is an unknown cost with a potentially very high ceiling.

When to Hand This Off

The content audit and SEO phases are largely systematic — given the right tools and enough time, a capable team can work through them. The content model redesign in phase two is where specialist knowledge makes the biggest difference. Getting the collection structure, relationship model, and access control right the first time prevents expensive re-architecture later. Getting it wrong means running the migration a second time or living with a system that accrues new technical debt from day one.

If your team is hitting uncertainty in phase two — how to model this content type, how to handle this relationship, how to structure access control for this workflow — that's the engagement point. The $500 System Mapping Session is a 60-minute architecture session that works through exactly these decisions. It applies toward any larger engagement if the project moves forward.

For teams that want the full migration handled end-to-end, the Payload CMS migration service covers principal-led migrations from WordPress, Contentful, Sanity, Strapi, AEM, Wix, and Drupal — architecture-first, no handoffs.

Conclusion

A CMS migration done well leaves you with a cleaner system, better-structured content, and an architecture that can actually support where the business is going. The checklist isn't long, but phase two — content model redesign — is the one that requires the most care and produces the most leverage. Every decision you get right there compounds positively through phases three, four, and five.

The platforms you can migrate to are ultimately secondary to the quality of the architecture decisions you make before the first import script runs.

Let me know in the comments if you have questions about any of the phases, and subscribe for more practical development guides.

Thanks, Matija

Strapi and Payload are the two closest tools in the headless CMS space. Both are Node.js. Both are self-hosted. Both organise content into collections. The migration is structurally simpler than anything involving WordPress or Contentful because you're not crossing architectural paradigms — you're translating between two systems that share the same DNA.

This guide covers the migration end-to-end: content model mapping, schema rebuild in TypeScript, data export and import, rich text conversion from Slate to Lexical, ID remapping, and admin customisation differences. There's also an honest section at the end on when the migration isn't worth doing. If you're still evaluating whether to switch at all, start with the Payload CMS vs Strapi comparison first.

Mapping Your Strapi Content Model to Payload

The good news is that Strapi and Payload use the same fundamental content primitives. The translation is mostly 1:1.

The one area that requires judgment is the component-to-Blocks translation. Repeatable components that drive variable page layouts — the kind where editors stack and reorder sections — map cleanly to Payload's Blocks field. Components that are structurally fixed and always present (SEO metadata, address objects) are better modelled as named groups or inline embedded objects. Make this decision before touching any code; it affects how your admin UI looks and how editors work with content.

Single Types in Strapi become Globals in Payload. The concept is identical: a single document per type, used for site-wide settings, navigation, or homepage content. The translation is mechanical.

Recreating Your Strapi Schema as Payload Collections

Let's work through a concrete example: an articles collection with a tags array, an author relationship to a users collection, and a rich text body. Here's what that looks like in Strapi's content-type JSON:

// File: src/api/article/content-types/article/schema.json
{
  "kind": "collectionType",
  "collectionName": "articles",
  "attributes": {
    "title": { "type": "string", "required": true },
    "body": { "type": "richtext" },
    "tags": { "type": "json" },
    "author": {
      "type": "relation",
      "relation": "manyToOne",
      "target": "plugin::users-permissions.user"
    }
  }
}

In Payload, the same collection is a TypeScript file in your codebase:

// File: src/collections/Articles.ts
import type { CollectionConfig } from 'payload'

export const Articles: CollectionConfig = {
  slug: 'articles',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'body',
      type: 'richText',
    },
    {
      name: 'tags',
      type: 'array',
      fields: [
        {
          name: 'tag',
          type: 'text',
        },
      ],
    },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users',
      hasMany: false,
    },
  ],
}

The translation is mostly mechanical. Field types map cleanly: string becomes text, richtext becomes richText, relations become relationship fields pointing to the target collection's slug.

One decision to make early: when using the PostgreSQL adapter, the idType option controls whether Payload uses serial integers or UUIDs as primary keys.

// File: payload.config.ts
import { postgresAdapter } from '@payloadcms/db-postgres'

export default buildConfig({
  db: postgresAdapter({
    pool: { connectionString: process.env.DATABASE_URI },
    idType: 'uuid', // or 'serial' — this affects the ID remapping step
  }),
  // ...
})

If you choose uuid, your Payload IDs will be UUIDs from the start, which makes the remapping table (covered in the relationships section) slightly cleaner to manage. If you stay with serial, IDs are auto-increment integers — the same format Strapi v4 used, which can reduce confusion during migration but makes cross-system ID matching trickier.

Once your collections are defined, follow the production schema migration workflow before running any import scripts — push: false and migration files only in production.

Exporting from Strapi and Importing into Payload

Step 1 — Export from Strapi

Strapi's Data Management feature (available from v4.6.0+) provides a CLI export command that produces a compressed archive of your content:

strapi export --no-encrypt --no-compress -f strapi-export

The --no-encrypt --no-compress flags give you an unencrypted tar you can inspect directly. Unpack it and you'll find:

strapi-export/
  entities/
    entities_00001.jsonl   # one JSON object per line, one file per chunk
    entities_00002.jsonl
  links/
    links_00001.jsonl      # relationship data
  schemas/
    schemas.jsonl          # your content type definitions
  metadata.json

Each line in the entity files is a JSON object representing one document. In Strapi v4, the identifier is a numeric id. In Strapi v5, you'll also find a documentId field — a stable string identifier introduced with the Document Service API.

Step 2 — Transform and Import

Here's a TypeScript script that reads the JSONL export, transforms the article documents, and imports them into Payload via the Local API:

// File: scripts/import-articles.ts
import payload from 'payload'
import config from '../payload.config'
import { createReadStream } from 'fs'
import { createInterface } from 'readline'
import path from 'path'

// Maps Strapi numeric IDs to newly created Payload IDs
export const articleIdMap = new Map<number, string>()

async function importArticles() {
  await payload.init({ config })

  const exportPath = path.resolve('./strapi-export/entities/entities_00001.jsonl')
  const rl = createInterface({
    input: createReadStream(exportPath),
    crlfDelay: Infinity,
  })

  for await (const line of rl) {
    const record = JSON.parse(line)

    // Filter to the articles collection only
    if (record.__type !== 'api::article.article') continue

    const doc = await payload.create({
      collection: 'articles',
      data: {
        title: record.title,
        body: record.body, // rich text handled separately — see next section
        tags: (record.tags ?? []).map((t: string) => ({ tag: t })),
        // relationships resolved in second pass
      },
    })

    // Store the mapping: Strapi ID → Payload ID
    articleIdMap.set(record.id, doc.id as string)
    console.log(`Imported article ${record.id} → ${doc.id}`)
  }

  console.log(`Done. Imported ${articleIdMap.size} articles.`)
  process.exit(0)
}

importArticles()

[!NOTE] This script uses Payload's Local API (payload.create), which runs directly in Node without an HTTP layer. For CLI-based imports against a running Payload instance, the @payloadcms/sdk is the cleaner option — it handles auth and gives you the same find, create, update, and delete methods over HTTP.

Relationships are intentionally left out of the first pass. They're handled separately in the ID remapping step after all documents exist.

Converting Strapi's Rich Text to Payload's Lexical Format

This is the most technically involved part of the migration, and the part that every other guide skips entirely.

Strapi v4 and v5 both ship a Slate-based rich text editor as the default. Payload 3.x uses Lexical (@payloadcms/richtext-lexical). The node schemas are different, and data stored in one format cannot be read directly by the other.

Here's the structural difference for a heading node. In Strapi's Slate output:

{
  "type": "heading",
  "level": 2,
  "children": [{ "text": "Section title" }]
}

In Payload's Lexical format (SerializedHeadingNode):

{
  "type": "heading",
  "tag": "h2",
  "children": [{ "type": "text", "text": "Section title", "version": 1 }],
  "direction": "ltr",
  "format": "",
  "indent": 0,
  "version": 1
}

The structure is similar enough to convert programmatically. Here's a converter that handles the common node types:

// File: scripts/slate-to-lexical.ts

type SlateNode = {
  type?: string
  level?: number
  url?: string
  text?: string
  bold?: boolean
  italic?: boolean
  underline?: boolean
  children?: SlateNode[]
}

type LexicalNode = Record<string, unknown>

export function convertSlateToLexical(slateNodes: SlateNode[]): LexicalNode {
  return {
    root: {
      type: 'root',
      children: slateNodes.map(convertNode),
      direction: 'ltr',
      format: '',
      indent: 0,
      version: 1,
    },
  }
}

function convertNode(node: SlateNode): LexicalNode {
  // Text leaf node
  if (node.text !== undefined) {
    return {
      type: 'text',
      text: node.text,
      format: getTextFormat(node),
      version: 1,
    }
  }

  const children = (node.children ?? []).map(convertNode)

  switch (node.type) {
    case 'paragraph':
      return { type: 'paragraph', children, direction: 'ltr', format: '', indent: 0, version: 1 }

    case 'heading':
      return {
        type: 'heading',
        tag: `h${node.level ?? 2}`,
        children,
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
      }

    case 'list':
      return {
        type: 'list',
        listType: 'bullet',
        children,
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
        start: 1,
        tag: 'ul',
      }

    case 'list-item':
      return {
        type: 'listitem',
        children,
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
        value: 1,
      }

    case 'link':
      return {
        type: 'link',
        url: node.url ?? '',
        children,
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
        fields: { url: node.url ?? '', newTab: false },
        rel: 'noreferrer',
        target: null,
        title: null,
      }

    default:
      // Fall back to paragraph for unknown types
      return { type: 'paragraph', children, direction: 'ltr', format: '', indent: 0, version: 1 }
  }
}

function getTextFormat(node: SlateNode): number {
  let format = 0
  if (node.bold) format |= 1
  if (node.italic) format |= 2
  if (node.underline) format |= 8
  return format
}

[!WARNING] Payload 3.79.0 upgraded the internal Lexical dependency from 0.35.0 to 0.41.0. The release notes confirm all breaking changes are handled internally — no action required for standard usage. Custom Lexical node converters should still be validated after a Payload version upgrade.

Use the converter in the import script by replacing the body field:

// In import-articles.ts
import { convertSlateToLexical } from './slate-to-lexical'

// Inside the import loop:
data: {
  title: record.title,
  body: record.body ? convertSlateToLexical(record.body) : undefined,
  // ...
}

Test a handful of documents manually before running the full import. Edge cases like nested lists or Strapi-specific custom blocks will need their own case branches added to the converter.

Remapping Strapi IDs to Payload IDs

Strapi v4 uses auto-increment integers as primary keys. Strapi v5 adds documentId — a stable string — but the underlying id is still a numeric integer. Payload's PostgreSQL adapter uses either serial integers or UUIDs depending on your idType config. MongoDB Payload stores stringified ObjectIds.

The problem: you can't insert a Strapi ID into a Payload relationship field and expect it to resolve. The ID formats are incompatible, and even if they happened to match numerically, Payload's relationship fields store Payload document IDs.

The solution is a two-pass import. Pass one creates all documents (articles, authors, tags — any collection involved in a relationship) and builds a mapping table. Pass two resolves relationships using that table.

Here's the second pass for the articles collection, linking the author relationship:

// File: scripts/import-article-relations.ts
import payload from 'payload'
import config from '../payload.config'
import { articleIdMap } from './import-articles'
import { authorIdMap } from './import-authors' // built in a separate first-pass script
import { createReadStream } from 'fs'
import { createInterface } from 'readline'
import path from 'path'

async function importArticleRelations() {
  await payload.init({ config })

  const linksPath = path.resolve('./strapi-export/links/links_00001.jsonl')
  const rl = createInterface({
    input: createReadStream(linksPath),
    crlfDelay: Infinity,
  })

  for await (const line of rl) {
    const link = JSON.parse(line)

    // Filter to article → author relations only
    if (
      link.__type !== 'api::article.article' ||
      link.field !== 'author'
    ) continue

    const payloadArticleId = articleIdMap.get(link.entity_id)
    const payloadAuthorId = authorIdMap.get(link.related_id)

    if (!payloadArticleId || !payloadAuthorId) continue

    await payload.update({
      collection: 'articles',
      id: payloadArticleId,
      data: {
        author: payloadAuthorId,
      },
    })
  }

  console.log('Relations resolved.')
  process.exit(0)
}

importArticleRelations()

Run all first-pass scripts (one per collection) before running any second-pass relationship scripts. The order matters: a relationship target must exist in Payload before you can reference it.

[!TIP] Export your articleIdMap, authorIdMap, and any other mapping tables to JSON files on disk between passes. If a second-pass script fails midway, you won't need to re-run the full first pass to recover the mapping state.

What Happens to Your Strapi Admin Customisations?

If your team has built Strapi admin customisations, the mental model shifts significantly.

In Strapi, admin customisation uses named injection zones: you register components via bootstrap and register hooks in src/admin/app.tsx, targeting specific named zones in the admin UI (contentManager.editView.informations, for example). The layout is fixed; you're injecting into predefined slots.

In Payload, customisation is declared directly in the collection config via the admin.components field. You own the component slots — header, beforeList, afterList, Description, and others — and render your own React components there. There's no injection zone API to learn; it's just React props in TypeScript.

// File: src/collections/Articles.ts (admin customisation)
export const Articles: CollectionConfig = {
  slug: 'articles',
  admin: {
    components: {
      beforeList: [() => import('./components/ArticleStats')],
      Description: () => import('./components/ArticleDescription'),
    },
  },
  fields: [...],
}

If you've built Strapi plugins using @strapi/sdk-plugin — particularly anything that hooks into plugin content type lifecycles — those will need a complete rewrite as Payload hooks or custom admin components. The good news is the resulting code is simpler: everything lives in your repository, typed, no plugin registration ceremony.

For a full walkthrough of what's available in Payload's admin component system, the Payload CMS Admin UI custom components guide covers the patterns in detail.

When the Migration Isn't Worth It

This section exists because not every Strapi project should move to Payload. Three situations where the ROI isn't there:

Your content team manages their own schema. Strapi's visual content type builder lets editors and non-technical team members add fields, create new content types, and modify schemas without touching code or triggering a deployment. Payload removes this entirely — every schema change is a TypeScript edit and a code deploy. If your organisation has editors managing their own content model, this isn't a DX improvement, it's a regression.

You're running three or more Strapi plugins for core functionality. Strapi's plugin ecosystem has over 400 community packages. Payload's is curated and growing, but materially smaller. If your project depends on Strapi plugins for search integration, payment processing, localisation workflows, or enterprise SSO, check whether Payload has equivalents before starting the migration. In some cases you'll be rebuilding features, not migrating content.

Your team doesn't work in TypeScript. Payload's configuration, schema definitions, access control, and hooks are all TypeScript throughout. There's no escape hatch. A team without TypeScript fluency will struggle to maintain a Payload codebase and won't get the benefits that make the migration worthwhile in the first place.

If none of these apply — you have an engineering-led team, a manageable plugin footprint, and TypeScript as a baseline — the migration is straightforward and the long-term DX improvement is real. For a broader view of what Payload offers compared to the headless CMS landscape, the best headless CMS for Next.js guide is worth reading before committing.

Ready to Migrate?

This guide covered the full migration path: content model mapping, TypeScript schema rebuild, Strapi export and Payload import, Slate to Lexical rich text conversion, ID remapping with a two-pass approach, and admin customisation differences.

If your team would rather hand the migration off than run it in-house, the Payload CMS migration service covers end-to-end migrations from Strapi, Contentful, WordPress, and Sanity.

Let me know in the comments if you run into edge cases not covered here — particularly around Strapi dynamic zones or custom field types — and subscribe for more practical Payload guides.

Thanks, Matija

Why Most Construction Website Roundups Are Useless

Search "best construction websites" and you will get roundups featuring Turner Construction, Bechtel, and PCL — companies with dedicated marketing departments, six-figure design budgets, and global brand recognition. That is not useful context for a 20-person general contractor in the Midwest deciding what to build.

This article looks at construction websites that work for real businesses: companies between 10 and 50 employees that compete on referrals, regional reputation, and the quality of a portfolio page rather than brand equity alone. The examples here were selected for one reason — they make specific, defensible decisions that a similar-sized firm can learn from and replicate.

Section 1: What Makes a Construction Website "The Best"

Before listing examples, it is worth defining the criteria. Without a framework, any list of websites is just a collection of opinions about aesthetics.

A portfolio that stays current. This is the single most important technical decision in a construction website build. If the owner needs to call a developer to add a new project, the portfolio will fall behind — and a stale portfolio communicates to every visitor that the company is either slow, inactive, or indifferent. The right architecture gives the owner a CMS interface where they can add a project with photos, a title, a description, and a category in under ten minutes. That is a structural decision made at the build stage, not something that can be retrofitted easily.

Mobile performance. Construction buyers frequently evaluate contractors on-site — meaning on a phone, with a mediocre data connection, between meetings or site walks. A website that loads slowly or displays a broken layout on mobile loses those evaluations silently. No one sends an email to explain why they left.

A clear inquiry path. How many clicks does it take from the homepage to a submitted quote request? On strong construction websites, the answer is one or two. The contact form is not buried in a footer — it is accessible from the navigation and often from project pages directly.

Specific service pages. "We build great things" is copy that applies to every construction company on the planet. The websites that win clients describe real capabilities: specific project types, typical project scales, sectors served, geographic coverage. A visitor should be able to read a services page and know within 60 seconds whether this company can do what they need.

Real trust signals. Team photos, years in business, actual project photography — these convert better than stock imagery or generic credibility claims. A photo of the actual crew on an actual site communicates more trust per pixel than a stock photo of a hard hat on a clean desk.

If you want a full breakdown of the page structure that covers these elements, see what a construction company website should include.

Section 2: Real Examples — What They Do Well and Why It Works

Lankes.si — Content Ownership at the Foundation

Lankes is a Slovenian construction company that came to me with a familiar problem: a website that looked fine but required developer involvement every time something changed. The owner wanted to add new projects, update service descriptions as their work evolved, and do both without filing a ticket or waiting for a callback.

The build used Next.js on the frontend for fast load times and Payload CMS on the backend for content management. The architecture decision was deliberate: Payload gives a non-technical user a clean admin interface where adding a new project means filling in a form — project name, location, scope, photo upload — and hitting publish. No developer. No delays. No portfolio that quietly goes stale over the following 18 months.

The result is a construction website where content ownership sits with the business, not with a vendor. The owner can document a project the week it's completed, which means the portfolio reflects current work rather than the projects that happened to get added during the last developer engagement. That freshness is visible to both visitors and search engines.

This is the kind of decision that determines the long-term value of a construction website. The frontend design can always be updated; if the CMS is wrong from the start, the portfolio will always be a point of friction.

Boneks — When the Website Connects to Operations

Boneks is a construction-adjacent company built around a fundamentally different question: what happens when a website connects to operational tooling instead of just serving as marketing?

Most construction websites are passive — they present information and wait for someone to reach out. The Boneks approach wires the website into the actual business workflow. Quote requests flow into a structured pipeline. Project documentation is accessible through the site rather than scattered across email threads. The website becomes a tool that the business uses internally as much as clients use it externally.

This matters for construction firms because the inquiry-to-proposal process is where most of the friction lives. A visitor submits a contact form, it lands in a general inbox, someone follows up days later with a generic reply. The alternative is a site built with a clear operational model: inquiry capture with structured fields, automatic routing, and a documented follow-up path. The website is not separate from how the business works — it is part of it.

ARheko — Specificity as a Competitive Signal

ARheko takes a similar framing to Boneks. The website architecture here prioritizes specificity at every level: services are described with the precision of a company that has done the work hundreds of times, project pages carry enough detail that a potential client can evaluate fit before picking up the phone, and the inquiry path is structured around the specific information needed to start a conversation.

What this communicates to a visitor is competence. A services page that uses industry-specific language — that describes real equipment, real processes, real project types — reads differently from a page that says "we handle all aspects of construction with quality and professionalism." The latter describes every contractor who has ever existed. The former describes this one.

The structural lesson is that specificity is a design decision, not just a copywriting decision. It requires a CMS that lets the owner maintain detailed service descriptions over time as the business evolves, not one where updating a page involves a developer and a project scope.

Tuckman-Barbee Construction — 75 Years of Evidence, Not Claims

Tuckman-Barbee is a Maryland general contractor founded in 1946. Their website at tuckman.com makes one decision brilliantly: it leads with proof, not assertions.

Where many construction websites open with generic taglines, Tuckman-Barbee opens with client names — the US Army Corps of Engineers, Johns Hopkins Health System, Georgetown University, the United States Naval Academy. These are not testimonial quotes in a scrolling carousel. They are listed as part of the site's core content, treated as evidence of capability rather than social proof afterthought.

The portfolio structure follows the same logic. Projects are documented with enough specificity that a visitor working in healthcare construction, for example, can immediately find relevant work. The navigation is clean and the mobile experience is functional — nothing revolutionary, but it doesn't need to be. The credentials do the work.

The lesson here is about where trust signals live on the page. Burying client names in a footer or a separate testimonials section means most visitors never see them. When those names appear in the primary content hierarchy, they function as qualification signals rather than decoration.

Greiner Construction — Sector Pages That Earn Organic Traffic

Greiner is a commercial general contractor in Minneapolis. Their website at greinerconstruction.com demonstrates a specific SEO and conversion architecture that mid-market construction firms consistently underuse: dedicated pages for each market sector they serve.

Rather than a single services page listing everything Greiner can build, the site has individual pages for healthcare, multi-family, office/workplace, retail, and other sectors. Each page describes specific work within that sector, links to relevant completed projects, and gives a potential healthcare client — for example — enough context to determine fit without calling first.

This structure serves two functions simultaneously. For search, it creates targeted landing pages that can rank for terms like "healthcare construction Minneapolis" rather than competing for the generic "construction company Minneapolis" term against every firm in the market. For conversion, it removes the qualification burden from the phone call. A visitor who has already read the healthcare sector page and seen three relevant completed projects is a different kind of inquiry than one who found a generic homepage.

The decision to build sector pages is a content architecture decision made at the sitemap level. It requires a CMS where adding a sector page and linking it to relevant project portfolio entries is a natural workflow — not a custom development task.

Section 3: What the Best Construction Websites Have in Common

Looking across these examples, several patterns appear consistently.

The CMS matches the owner's workflow. Every construction company has a point of friction where the website falls behind reality. Projects get completed and don't get added. Services evolve and the page doesn't. The firms with strong websites have solved this structurally — the CMS makes content updates the path of least resistance, not a task that requires scheduling a developer.

Portfolio pages carry real detail. Strong construction portfolio entries include project name, location, scope, scale, and actual photography. Weak ones are photo galleries with no labels. The detail serves two purposes: it helps visitors self-qualify, and it gives search engines something to index beyond image metadata.

The inquiry path is visible from every page. On every strong construction website reviewed here, a visitor can get to a contact form from wherever they are on the site. Navigation includes a contact link. Project pages include a call-to-action. The friction between "interested" and "submitted an inquiry" is minimal.

Trust signals are content, not decoration. Client names, years in business, team photos, and project photography appear in the main content hierarchy — not relegated to a sidebar, a footer, or a testimonials section that most visitors never scroll to.

Mobile performance is treated as a primary constraint. Fast load times on mobile are not a bonus feature — they are the baseline. Construction buyers are often evaluating on phones, and a site that takes four seconds to load on a 4G connection loses those evaluations to a competitor whose site loads in one.

Section 4: What to Avoid

The failure modes in construction websites tend to be consistent. These are the decisions that quietly cost leads.

A portfolio gallery with no project details. A grid of photos without titles, descriptions, or project context looks abandoned. It also fails to communicate what type of work the company does, what scale they operate at, or who their past clients are. A visitor cannot self-qualify on photos alone.

No CMS — the owner cannot update without calling a developer. This is the most common problem in construction websites built more than two years ago. The site looks fine initially, and then slowly becomes an inaccurate representation of the business as work evolves and no one updates the content.

Slow load times from unoptimized project photos. Construction portfolios involve large, high-quality images. Without optimization — proper compression, modern image formats, lazy loading — a portfolio page with 20 project photos can easily take 8–10 seconds to load on mobile. That kills the experience for the visitors most likely to be evaluating on-site.

A contact form buried in the footer. If the only path to an inquiry is through a footer link, many visitors will leave without contacting. The contact form should appear in the navigation, and construction websites with strong conversion rates typically include a CTA on project pages and the services page as well.

Generic services copy. "We deliver quality construction projects on time and on budget" describes no company in particular. Services pages that describe specific project types, typical scales, materials, methods, and sectors attract qualified visitors and convert better because they demonstrate familiarity with the work — not just a willingness to do it.

FAQ

What makes a good construction company website?

A good construction company website does three things well: it shows completed work in enough detail that visitors can evaluate fit, it describes services with enough specificity that generic contractors can be eliminated, and it makes it easy to request a quote or start a conversation. CMS architecture — meaning whether the owner can maintain the site without developer involvement — determines whether the website stays accurate over time.

How do I choose a CMS for a construction company website?

The right CMS for a construction website is one that the business owner can use without technical training. For custom-built sites, Payload CMS offers a clean admin interface that can be configured to match a construction company's exact content model — project types, service categories, team members. For simpler builds, WordPress with a well-configured theme works if the project budget doesn't support custom development. The key question is: can the owner add a new project and update a services page without calling a developer?

How often should a construction company update its website portfolio?

After every completed project, ideally within the same week. Portfolio recency signals to visitors that the business is active, and to search engines that the site is maintained. A construction website with no portfolio additions in 12 months reads as inactive regardless of how good the design is. The reason most portfolios fall behind is a structural one — the CMS makes updates difficult. Fix that first.

What pages should a construction company website have?

At minimum: a homepage, a services page or sector-specific service pages, a portfolio or projects section, an about page with team information, and a contact page. Construction companies serving multiple industries benefit from dedicated sector landing pages (healthcare construction, commercial construction, etc.) rather than a single services page. Each sector page can rank independently in search and helps visitors self-qualify before contacting.

How much does a good construction website cost?

A functional construction website built on a standard CMS can cost between €2,000 and €6,000 depending on the scope of content, number of pages, and level of custom design. A custom-built site on Next.js and Payload CMS — with a properly configured project portfolio, sector pages, and a content model the owner can maintain independently — typically runs €6,000 to €15,000. The right question isn't the upfront cost but the total cost over three years: a site that requires a developer for every content update will cost more over time than one built with content ownership in mind from the start.

If you're evaluating web partners for a construction company website, our construction website design services page covers what we build and how we approach the work.

Thanks, Matija