TYPO3 headless mit Next.js

Klassisches TYPO3, serverseitig mit Fluid gerendert, ist für die meisten Projekte die richtige Wahl — auch bei mir ist das die Regel, nicht die Ausnahme. Headless lohnt sich, wenn das Frontend eigene Anforderungen mitbringt: App-artige Interaktivität mit React, ein Frontend-Team mit eigenem Stack, mehrere Abnehmer für denselben Content oder ein Backend, das aus dem öffentlichen Netz verschwinden soll.

Ein Argument gewinnt dabei an Gewicht: Moderne Bibliotheken erscheinen heute zuerst als React-Komponenten. Ein 3D-Viewer mit Three.js, ein Chat-Interface über das AG-UI-Protokoll, Karten, Charts, interaktive Konfiguratoren — im Next.js-Frontend ist das ein Import und eine Komponente mit gepflegter Dokumentation. In serverseitig generiertes Fluid-HTML lässt sich dasselbe zwar einbauen, aber als Eigenbau gegen die Bibliothek statt mit ihr: eigenes Bundling, eigene Initialisierung, kein Komponenten-Modell. Je mehr solcher Bausteine ein Projekt braucht, desto stärker zieht die Rechnung Richtung headless.

Dieser Guide zeigt den zweiten Fall: TYPO3 liefert JSON, Next.js rendert. Alles Folgende läuft produktiv auf dieser Site — die Codebeispiele sind daraus destilliert, nicht aus einem Tutorial-Projekt. Was headless konzeptionell bedeutet und wann es sich rechnet, steht ausführlicher unter Headless TYPO3.

Warum Next.js und nicht Nuxt?

Das offizielle Referenz-Frontend für EXT:headless ist nuxt-typo3 — Vue und Nuxt. Wer dort startet, bekommt fertige Komponenten für die Standard-Inhaltselemente. Ich arbeite trotzdem mit Next.js: Das React-Ökosystem ist größer, Server Components und App Router passen gut zum Muster „ein JSON-Dokument pro Seite“, und die Frontend-Kompetenz vieler Teams liegt heute bei React. Die Anbindung an TYPO3 ist in beiden Fällen dieselbe JSON-API — dieser Guide zeigt den Next.js-Weg, weil es dafür deutlich weniger dokumentierte Praxis gibt.

Die Extension friendsoftypo3/headless übernimmt die komplette JSON-Ausgabe — Seitenbaum, Navigation, Inhaltselemente, Mehrsprachigkeit inklusive Fallbacks:

composer require friendsoftypo3/headless

Ab TYPO3 v13 wird die Extension als Site-Set eingebunden. Das eigene Site-Set deklariert headless als Abhängigkeit:

# Configuration/Sets/MySite/config.yaml
name: my/site
dependencies:
  - friendsoftypo3/headless

Auf der Next.js-Seite (App Router) reichen zwei Routen: app/page.js für die Startseite und eine Catch-all-Route für alles andere. Die Route holt das JSON der angefragten Seite und rendert die Inhaltselemente:

// app/[...slug]/page.js
export default async function Page({ params }) {
  const { slug } = await params
  const res = await fetch(
    `${process.env.NEXT_PUBLIC_DOMAIN_HEADLESS}/${slug.join('/')}`,
    { cache: 'force-cache' }
  )
  const page = await res.json()
  return page.content.colPos0.map((ce) => <CE ce={ce} key={ce.id} />)
}

generateMetadata() holt dasselbe JSON für Title und Meta-Description — Next.js dedupliziert die beiden Fetches automatisch.

Das Herzstück ist ein einziger Dispatcher: eine Komponente, die über ce.type verzweigt. Ein neues Inhaltselement im Backend heißt im Frontend genau ein neuer case plus eine Komponente. Alles Unbekannte fällt auf eine sichtbare Fallback-Komponente zurück — so sehen Sie im Entwicklungsmodus sofort, welches Element noch keine Entsprechung hat.

Für RTE-Inhalte hat sich html-react-parser bewährt: Das HTML aus bodytext wird geparst, interne Links werden dabei zu Next.js-<Link>-Komponenten (Client-Navigation ohne Full-Page-Load), externe bekommen rel="noopener noreferrer".

Bilder liefert die API als fertige Objekte: öffentliche URL auf die verarbeitete Datei (Crops aus dem Backend bereits angewendet), Abmessungen, Alt-Text. Auf Wunsch erzeugt TYPO3 zusätzliche Varianten — WebP, Retina, Platzhalter in niedriger Auflösung. Im Frontend übernimmt next/image die Auslieferung; dafür muss die TYPO3-Domain in next.config.mjs unter images.remotePatterns für den /fileadmin/-Pfad freigeschaltet sein.

Ein Punkt, der in Headless-Projekten gern durchrutscht: Der Alt-Text steht im JSON unter properties.alternative — die Frontend-Komponente muss ihn auch verdrahten. Gepflegte Alt-Texte im Backend nützen nichts, wenn die Komponente alt="" rendert.

Redirects gehören an eine Stelle

In einer entkoppelten Architektur konkurrieren drei Orte um Redirects: TYPO3, der Webserver, das Frontend. Entscheiden Sie sich für einen. Bei mir liegen SEO-Redirects zentral in der Next.js-Konfiguration — versioniert im Git des Systems, das die Anfrage zuerst sieht.

Vorschau für Redakteure

Die Vorschau versteckter Seiten funktioniert über Backend-Cookies — und Cookies brauchen eine gemeinsame Root-Domain. api.example.org neben example.org funktioniert mit passender cookieDomain-Konfiguration; völlig getrennte Domains für Backend und Frontend funktionieren nicht ohne Zusatzaufwand. Das ist ein Argument bei der Domain-Planung, nicht erst beim Go-live.

Sitemap-URLs prüfen

Die XML-Sitemap generiert TYPO3 — das Backend kennt aber erstmal nur die eigene API-Domain. Ohne Konfiguration der Frontend-Basis stehen API-URLs in der Sitemap. Nach dem Go-live als Erstes prüfen.

Formulare funktionieren — anders als gewohnt

EXT:form läuft headless weiter, nur die Arbeitsteilung verschiebt sich: TYPO3 liefert die Formular-Definition als JSON — Felder, Typen, Validierungsregeln —, das Frontend baut daraus das Markup und schickt die Eingaben per POST zurück. Validierungsfehler kommen strukturiert als JSON zurück, nicht als fertige HTML-Seite; die Fehlerdarstellung ist damit Frontend-Aufgabe. Das ist der Bereich mit den meisten Community-Fragen zur Extension.