Skip to content
McGinnPublishing
02Architecture & Systems

How WordPress and Next.js actually fit together.

Monoliths fail at the theme layer. We decouple authoring from rendering with a typed content pipeline, edge caching, and zero compromises on editorial workflow.

Model
3-tier decoupled pipeline
API layer
WPGraphQL + REST fallback
Edge delivery
ISR with on-demand tags
01The challenge

WordPress was never the problem. The theme was.

A monolith WordPress site has a CMS bolted to the front of it and a database buried in the middle. Editors get a page builder. Developers get a plugin dependency tree. Marketing gets a page speed nobody will defend. Headless WordPress keeps the part that works and rebuilds the part that does not.

The usual outcome

A replatform is commissioned, the old stack is retired, and twelve months later the business is arguing about the redirect map. The rebuild was never the thing that was broken.

  • 01

    The theme is a second CMS nobody owns

    Once a page builder lands, the layout becomes content — but content nobody can version, test or roll back. The design system lives inside a vendor plugin, and the marketing team can break the checkout flow with a drag and drop.

    Every front-end change needs a plugin licence, a CSS override and a prayer.

  • 02

    Plugin sprawl is a supply-chain risk

    The average commercial WordPress site runs forty to sixty plugins. Each one is code with database access, running on the same origin as checkout. Two of them are usually unmaintained and one is quietly sending newsletters.

    A patch cycle you cannot complete and an incident surface you cannot enumerate.

  • 03

    The origin sits in front of every request

    PHP renders the document, then plugins inject stylesheets and scripts, then the browser discovers there is more to download. Time to first byte is whatever your host feels like. There is no cache in front of the origin because the page is personalised by assumption.

    Traffic on launch day is a capacity incident, not a growth story.

  • 04

    Editorial and commerce cannot share a page

    A long-form feature about a product has to live in one template and a product listing cannot carry an argument. The compromise is always the same: the story becomes a PDF, the product becomes a set of bullet points, and the argument lives in a widget nobody trusts.

    The most valuable content on your site earns the least attention.

  • 05

    The migration is treated as a rewrite

    Platforms get sold as clean-sheet builds, which means the eleven thousand URLs, the accumulated redirects and eight years of accumulated SEO equity all have to be re-earned from nothing. The business case quietly assumes you were starting from zero.

    You pay for a new website when you needed a new front end.

  • 06

    Nobody owns the rendering strategy

    Some pages should be static HTML. Some need to be fresh every request. Some sit in between. Without a decision recorded per route, the default wins — and the default is server-rendering everything through WordPress.

    You pay for a database round trip on every page view, forever.

Monolith vs. headless, honestly

We build the right column
Comparison of a monolithic WordPress build against a headless WordPress build with a Next.js frontend
DimensionMonolithic WordPressHeadless + Next.js
Editor experiencePage builder holds the layout; layouts are not versionedBlock editor holds content; layout comes from a tested component
Design changesVendor plugin update, CSS override, or bothGit pull request, visual diff, one-minute release
RenderingPHP on the origin for every requestStatic or edge-rendered by default, dynamic where required
CachePage cache plugins that break on cookiesCDN cache keyed on content revision
CommerceA plugin that reinvents checkoutStorefront API into a platform that does checkout properly
Third-party scriptsRender-blocking tags injected by pluginsThird-party scripts isolated from the critical path
Attack surfaceSixty plugins on the checkout originRead-only public GraphQL; admin never exposed
Analytics ownershipVendor owns the tag managerYou own the event layer and the data

The honest caveat: headless is not free. You are running two systems, you need someone who knows both, and a page that could have been a template is now an engineering decision. We will tell you when a build does not need it.

02The architecture

WordPress keeps the editing. Next.js keeps everything else.

Three layers, one direction of travel. Nothing in the authoring layer is allowed to decide how a page looks, and nothing in the delivery layer is allowed to be slow.

Authoring

WordPress

Editorial source of truth. Block editor, revisions, roles.

  • WP 6.5
  • ACF Pro
  • Gutenberg

Commerce platform

Catalogue, pricing, tax, fraud, basket and checkout.

  • Shopify
  • Storefront API
  • Stripe

Media library

Originals and derivatives, served through an image pipeline.

  • R2
  • next/image
  • AVIF/WebP
publish → tag → invalidate

Delivery

WPGraphQL

Typed content API. Read-only for the public, private for preview.

  • GraphQL
  • Schema locks

Edge cache

Static shell and content fragments, revalidated on publish.

  • ISR
  • SWR
  • Tags
cached HTML + minimal JS

Experience

Next.js

Server Components render HTML. Islands hydrate on interaction.

  • App Router
  • RSC
  • TypeScript

Commerce and media bypass the content API — the server layer queries those platforms directly.

The CMS origin is never exposed to the browser and never renders a page.

Rendering strategy, written down per route

The decision that separates a fast platform from an expensive one is made once, early, and recorded. Here is ours, abridged from a live architecture decision record.

Rendering strategy per route type, with the reason recorded
RouteStrategy
Product & categoryStatic + tag revalidation
Long-form featuresStatic shell, streamed body
Search & autocompleteDynamic, no-store
Basket & accountDynamic, edge runtime
Preview / draftsUncached, authenticated

The CMS never renders a page

WordPress is a content database with an excellent editing interface. It returns typed JSON. Rendering decisions belong to the frontend, where they can be tested and deployed independently.

Rendering is decided per route

Product category pages are static and revalidate on publish. Search is dynamic. Article pages stream. Recording that decision per route is what separates a fast platform from an expensive one.

Preview renders the real components

Draft preview uses the production component tree against an authenticated query. If it looks right in preview, it will look right in production — because it is the same code.

Publish invalidates, it does not redeploy

A save in WordPress triggers a webhook that revalidates the affected tags at the edge. Editors see their change in seconds without a deploy and without a rebuild.

06The stack

Boring tools, chosen deliberately.

Nothing here is fashionable. Every component is widely supported, documented, and has a migration path if we ever need to replace it. The interesting decisions are in the rendering, not the tooling.

Content

  • WordPress

    Editorial CMS

    6.5+ with a curated plugin set

  • WPGraphQL

    Content API

    Schema locked to public queries

  • ACF Pro

    Field modelling

  • Gutenberg

    Block editor

  • Cloudflare R2

    Media origin

Frontend

  • Next.js

    App Router, React Server Components

  • TypeScript

    Strict mode, no `any` in the data layer

  • Tailwind CSS

    Design tokens as code

  • Storybook

    Component documentation and tests

  • Playwright

    End-to-end coverage

Commerce

  • Shopify

    Catalogue, basket, checkout

  • Storefront API

    Typed GraphQL product queries

  • Stripe

    Payments, subscriptions, invoicing

  • Algolia

    Search, faceting, autocomplete

Platform

  • Vercel

    Edge runtime, ISR, image optimisation

  • Upstash Redis

    Cart and session state

  • Sentry

    Error tracking, edge and browser

  • GitHub Actions

    CI gates and deployment

This site is built with the stack we sell. Its content layer falls back to typed local fixtures when no WordPress origin is configured, so it deploys and reviews without a CMS — the same resilience we build into client platforms.

05How we work

Five phases. No surprises.

Every engagement runs on the same spine. What changes is how much of each phase a given project needs — and we say so in the proposal rather than after the invoice.

Our default shape

12–20

weeks from first conversation to production traffic, including migration.

  1. 01

    Discovery

    1–2 weeks

    We find the actual problem

    Two weeks of reading the codebase, the analytics and the support tickets before anyone opens a design file. Most headless projects arrive described as a redesign and turn out to be a content-modelling problem or a checkout problem wearing a costume.

    • Stakeholder interviews across editorial, marketing and engineering
    • Technical audit of the current build, plugins and hosting
    • Core Web Vitals and conversion baseline from field data
    • Content inventory: what exists, what is used, what is dead

    OutputA written problem statement, risk register and scoped delivery plan.

  2. 02

    Architecture

    2 weeks

    We decide what renders where

    The single most consequential decision in any headless build is which pages are static, which are incremental, and which genuinely need a server. Get it wrong in either direction and you have either a stale storefront or a server that does no work.

    • Route-by-route rendering strategy
    • Content model design and field group specification
    • Integration contracts between CMS, commerce and search
    • Threat model for the public GraphQL surface
    • Preview and draft workflow design

    OutputArchitecture decision records, schema, and a rendered proof of concept.

  3. 03

    Design

    3–5 weeks

    We build the system, not the pages

    We build tokens and components rather than mockups of pages, because the second page is the one that reveals whether the system works. Editorial design gets treated with the same seriousness as product design.

    • Type scale, grid and colour tokens
    • Component library with Storybook documentation
    • Matching Gutenberg blocks for editorial-authored layouts
    • Motion and state specification per component
    • Accessibility pass against WCAG 2.2 AA

    OutputA component library your designers and developers both use.

  4. 04

    Build

    6–12 weeks

    We ship in thin, reversible slices

    Every slice is deployed behind a flag to real traffic on real devices. You see progress weekly, and every decision is reversible until the day we switch traffic for good.

    • Two-week sprints with a demo at the end of each
    • Content and commerce integration behind route flags
    • CI gates on types, lint, tests and bundle budget
    • Automated migration pipelines rehearsed on a copy of production
    • Parallel-run parity builds from week one

    OutputProduction traffic on the new stack, migrated and verified.

  5. 05

    Operate

    Ongoing

    We hand over something you can run

    Documentation, runbooks, architecture decision records and a training session with the people who will actually operate this. If you would rather we ran it, we will — under a retainer, with named engineers.

    • Runbooks and architecture decision records
    • Training sessions for editorial and engineering
    • Monitoring, alerting and on-call rota
    • Scheduled patching and dependency updates
    • Quarterly performance and roadmap reviews

    OutputA platform your team can operate, or ours to operate for you.

Architecture review

Planning a migration or replatform?

Send us your schema, traffic patterns, and plugin inventory. We can tell you within a week whether headless is the right posture for your team.

Request an architecture audit