Headless TYPO3 with Next.js: Architecture, Effort and When It Pays Off

I get asked the same thing in almost every project: “Can we keep TYPO3 and still get a fast, modern frontend?” The honest answer is yes, but not for free. In this article I show you what the architecture looks like, what is technically stable in October 2026, where the typical pitfalls are and when the rebuild really pays off for a mid-sized company.

What headless TYPO3 actually means

Headless means: TYPO3 only takes care of content, permissions, workflows and multilingual setup. A separate application, in our case Next.js, generates the HTML for visitors. In the classic setup, TYPO3 renders the page itself using Fluid templates and TypoScript.

Little changes for your editors. They keep working in the familiar backend with the page tree, content elements and approvals. What changes is everything behind it: hosting, deployment, caching and responsibility for the frontend now sit in two systems instead of one.

The difference from a pure headless CMS such as Strapi or Contentful: TYPO3 comes with a page structure. You don't just get records, you get complete pages with navigation, breadcrumbs, language variants and SEO fields. That is the real reason to run TYPO3 headless instead of switching CMS altogether.

The architecture at a glance

The setup has three parts: TYPO3 as the content source, Next.js as the rendering layer, and the browser. The bridge between TYPO3 and Next.js is EXT:headless, which outputs every TYPO3 page as JSON instead of HTML.

Next.js fetches the page JSON, caches it and serves finished HTML. When editors save, TYPO3 sends a webhook and Next.js discards exactly the affected cache entries. For preview, Next.js fetches content uncached directly from TYPO3.

Status in October 2026: what is stable and what isn't?

The most important news first: TYPO3 v14 LTS is here, but EXT:headless for v14 is still a release candidate. If you start a production project today, you have to plan for this gap deliberately.

Sources: the TYPO3 v14 LTS press release and the EXT:headless 5.0.0-rc1 release notes.

Two details from the release candidate are worth knowing. The old PreviewController XClass has been removed because TYPO3 v14 ships its own preview. And the final preview integration is still disabled in the RC. For editorial teams that rely heavily on preview and workspaces, that is not a detail but a project risk.

On the Next.js side: keep your version current. In May 2026, Vercel closed thirteen security vulnerabilities at once with 16.2.6. A headless frontend is a product of its own with its own patch cycle.

How to build it: the six building blocks

Every headless TYPO3 project with Next.js has to answer the same six questions. Forget one and you will notice on the first day the editors use it.

1. Routing: one route for all pages

Editors maintain the page tree in TYPO3. Next.js shouldn't rebuild it but pass every URL through to TYPO3. An optional catch-all route is enough:

// app/[[...slug]]/page.tsx
import { notFound } from 'next/navigation';
import { getPage } from '@/lib/typo3';
import { ContentArea } from '@/components/ContentArea';

export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
  const { slug = [] } = await params;
  const page = await getPage('/' + slug.join('/'));
  if (!page) notFound();
  return <ContentArea elements={page.content?.colPos0 ?? []} />;
}

You handle multiple languages through the language prefix in the path, as defined in the TYPO3 site configuration. EXT:headless delivers navigation and the language menu through data processors.

2. Component mapping: one React component per content element

Every TYPO3 content element arrives as JSON with its type. You need a mapping from type to React component:

const registry = {
  text: TextBlock,
  textmedia: TextMedia,
  image: ImageGallery,
  form_formframework: Typo3Form,
};

export function ContentArea({ elements }) {
  return elements.map((el) => {
    const Component = registry[el.type] ?? Fallback;
    return <Component key={el.id} {...el.content} />;
  });
}

This is where most of the project effort goes. Every custom content element and every extension with frontend output needs a React counterpart. For EXT:news, EXT:solr, Powermail and EXT:container there are add-on extensions that deliver the JSON. You still build the React rendering yourself.

3. Caching: TYPO3 notifies, Next.js cleans up

Without caching, Next.js queries TYPO3 on every request and your performance advantage is gone. With Next.js 16 you cache the fetch explicitly and attach a tag:

import { cacheTag, cacheLife } from 'next/cache';

export async function getPage(path: string) {
  'use cache';
  cacheTag('typo3', `page:${path}`);
  cacheLife('days');
  const res = await fetch(`${process.env.TYPO3_URL}${path}`);
  return res.ok ? res.json() : null;
}

When editors save a page, TYPO3 sends a webhook to Next.js. The webhooks extension has been part of the core since TYPO3 v12. A route handler in Next.js checks the secret and calls revalidateTag('typo3', 'max') or the specific page tag.

The tricky part: when a record that appears on many pages changes, such as the navigation or a footer element, you need to invalidate more broadly. Plan for this from the start.

4. Preview: draft mode and workspaces

Editors want to see their changes before approval. In Next.js you enable draft mode through a protected route and then fetch content uncached directly from TYPO3. The preview links in the TYPO3 backend must point to the Next.js domain. As described above, exactly this part is still open in the v14 RC of EXT:headless. Test it first in your proof of concept.

5. Forms and login

EXT:headless outputs forms from the TYPO3 Form Framework as a JSON schema, including validation rules. You render the form in React and submit it back to TYPO3. Finishers such as sending emails keep running server-side in TYPO3. Frontend login via EXT:felogin follows the same principle, but you have to pass session cookies cleanly across two domains or through a proxy.

6. SEO: none of this happens automatically

TYPO3 delivers meta title, description, canonical, hreflang and Open Graph data in the JSON. You set them in Next.js via generateMetadata. Redirects from EXT:redirects can be resolved through EXT:headless or mapped in proxy.ts, the successor of middleware.ts in Next.js 16. Rendering has to happen on the server, otherwise AI crawlers see an empty page.

TYPO3 can keep generating the XML sitemap, but it has to point to the frontend URLs. After go-live, use a crawler to check that status codes, canonicals and hreflang match the previous state. How to approach this is covered in our article on migrating without losing SEO.

Effort and typical pitfalls

The effort depends almost entirely on one number: how many content elements and extensions your frontend has to render. The TYPO3 side is configured quickly with EXT:headless. The work is in the React frontend and the infrastructure in between.

I see these pitfalls in almost every project:

• Carrying over old content elements. Many TYPO3 instances have accumulated dozens of CTypes over the years, half of which nobody uses anymore. Clean up before the rebuild, or you will rebuild legacy in React.
• Underestimating RTE content. Body text from the rich text editor arrives as HTML with internal TYPO3 links. You have to convert them into Next.js links, otherwise every click reloads the whole page.
• Testing preview too late. If editors only discover at go-live that workspaces don't work properly, it gets expensive.
• Two teams, no ownership. If TYPO3 development and frontend work separately, you need a clear JSON contract between them. Otherwise every backend change breaks the frontend.

When it pays off and when it doesn't

Headless pays off when the frontend has to do more than a website. For a plain company site with a blog, classic TYPO3 is usually the cheaper and more honest solution.

A middle way that is often overlooked: EXT:headless has a mixed mode. The same TYPO3 site then delivers both classic HTML and JSON. You can build individual areas, such as a product finder or a customer portal, in Next.js and leave the rest as it is for now. For many mid-sized companies that is a lower-risk start than a complete rebuild.

One more point in the interest of honesty: if your team prefers Vue over React, Nuxt is the more obvious choice. For Nuxt there is nuxt-typo3, an official frontend package from the headless community. With Next.js you build this layer yourself. The trade-off between coupled and decoupled frontends may already be familiar from e-commerce: it is the same as with composable commerce with Shopware.

Conclusion: use case first, architecture second

Headless TYPO3 with Next.js is a solid option in 2026, but not an end in itself. TYPO3 v14 LTS gives you planning security until 2029, Next.js 16 a mature caching model. The weak spot lies in between: EXT:headless for v14 is still an RC, and preview is the part you need to test first.

My advice from practice: start with a proof of concept of two to three weeks. Take the five most important content elements, one form page and your editors’ preview workflow. Afterwards you know whether the rebuild pays off and have a solid estimate instead of a gut feeling. How to plan the project around it is covered in our website relaunch guide.

Thinking about rebuilding your TYPO3 website headless, or want to know whether a hybrid is enough? Talk to us. We look at your setup and tell you honestly which path fits your team and budget.

FAQ on headless TYPO3 with Next.js

Do I need an extension for headless TYPO3?

In practice, yes. The standard is EXT:headless, available as the Composer package friendsoftypo3/headless and developed with support from Macopedia. It outputs pages, content elements, navigation, forms and SEO data as JSON.

Does EXT:headless work with TYPO3 v14?

Yes, with version 5, which has been available as a release candidate since May 2026 and supports TYPO3 v14 only. For TYPO3 v12 and v13 there is the stable 4.x line.

Is there a ready-made Next.js package for TYPO3?

There is no official Next.js counterpart to nuxt-typo3. You build routing, component mapping, caching and preview yourself, as described above.

Can editors keep using preview?

Yes, via Next.js draft mode and adapted preview links in the TYPO3 backend. Test this part first, though, because the v14 integration in EXT:headless is not final yet.

Is headless TYPO3 faster than classic TYPO3?

Not automatically. It gets faster through clean caching in Next.js. A well-cached classic TYPO3 is often just as fast as a poorly cached headless setup.

Can I run only part of my website headless?

Yes. With the mixed mode of EXT:headless, the same site delivers HTML and JSON. This lets you build individual areas in Next.js and migrate the rest step by step.