Migration zu Next.js / Astro in Augsburg

Eine Contao-Seite lässt sich nach Astro oder Next.js umziehen, aber nicht per Knopfdruck. Contao speichert Seiten, Artikel und Inhaltselemente in getrennten Tabellen, verknüpft Bilder über UUIDs und baut Navigation, Formulare und News-Listen erst beim Aufruf zusammen. Vier Entscheidungen bestimmen den Umzug: welche Version noch Support hat, wie ich die Inhalte aus der Datenbank hole, ob Contao als Redaktionssystem bleibt und welche URL jede alte Seite bekommt. Die folgenden Abschnitte nehmen sie einzeln vor.

#Wie lange wird Ihre Contao-Version unterstützt?

Den Termin nennt der Release-Plan auf contao.org. Er kennt vier Stufen: Entwicklung, aktive Pflege mit Fehlerbehebungen, Langzeitunterstützung (weiter Fehlerbehebungen) und eine Sicherheitsstufe mit ausschließlich sicherheitsrelevanten Updates. Die Daten unten stammen von dieser Seite, Stand November 2026.

Zwei Folgerungen. Erstens: Läuft Ihre Seite auf 5.3, enden die Fehlerbehebungen in wenigen Monaten, die Sicherheitsupdates laufen noch ein Jahr länger. Das ist ein Termin, aber kein Grund zur Eile, denn ein Update auf 5.7 ist die kleinere Alternative zur Migration. Zweitens: 5.4 bis 5.6 haben laut Plan keine Langzeitstufe, ihre aktive Zeit ist vorbei. Contao 4 taucht in der Zeitleiste gar nicht mehr auf. Die Version steht in Ihrer composer.lock beim Paket contao/core-bundle.

Ob Sie migrieren, sollte deshalb nicht am Datum hängen, sondern an dem, was Sie mit der Seite vorhaben. Der Rest dieser Seite hilft bei dieser Frage.

#Wie Contao Inhalte ablegt

Ich lese die Datenbank, nicht das gerenderte HTML. Das Datenmodell steht im 5.x-Zweig des Contao-Repositorys auf GitHub (Datei core-bundle/contao/dca):

Daraus folgen Stolpersteine, die ich vor dem Export kenne.

Inhaltselemente tragen die Struktur. Ein Artikel ist nur ein Rahmen, den Text enthalten die Elemente darunter, jedes mit einem type. Der Fließtext liegt als HTML in text, die Überschrift als serialisiertes PHP-Array mit Wert und Ebene (Vorgabe a:2:{s:5:"value";s:0:"";s:4:"unit";s:2:"h2";}). Wer nur die Textspalte exportiert, verliert Überschriftenebenen und Reihenfolge.

Verschachtelte Elemente gibt es seit Contao 5.3. Akkordeon, Elementgruppe und Content-Slider enthalten Kindelemente. Früher markierten Start- und Stopp-Elemente den Bereich. Beide Formen kommen auf alten Seiten oft nebeneinander vor, ich lese beide.

Insert-Tags stecken im Text. In Fließtexten stehen Platzhalter wie {{link_url::12}}, {{article_url::12}}, {{news_url::12}} oder {{image::UUID}}. Contao ersetzt sie erst beim Rendern. Ich löse jeden zur neuen Adresse auf, sonst zeigt der Link nach dem Umzug ins Leere.

Include-Elemente sind keine Inhalte. Die Doku nennt: Artikel, Inhaltselement, Formular, Modul und Kommentare. Die ersten beiden sind Verweise auf andere Inhalte, ich löse sie auf. Formular, Modul (etwa Navigation oder News-Liste) und Kommentare erzeugen Ausgabe zur Laufzeit und brauchen eine eigene Entscheidung.

#Der Export in der Reihenfolge, die ich einhalte

1. Kopie und Sicherung. Ich arbeite an einer Kopie. Contao bringt dafür php vendor/bin/contao-console contao:backup:create mit, das eine Sicherung nach var/backups schreibt.
2. Dateien synchronisieren. Contao kennt nur Dateien, die in seiner Datenbank stehen. Per FTP hochgeladene Dateien erscheinen erst nach „Synchronisieren“. Ohne diesen Schritt fehlen sie im Export, auch wenn sie auf der Platte liegen.
3. Baum ablaufen. Seiten, dann Artikel, dann Elemente nach sorting. Unveröffentlichte und ausgeblendete Elemente sowie geschützte Bereiche für Mitgliedergruppen sortiere ich aus, damit nichts Nichtöffentliches in einem öffentlichen Build landet.
4. Dateien auflösen. Aus jeder UUID wird ein Pfad. Lade ich eine Datei gleichen Namens im Dateimanager neu hoch, behält sie laut Doku ihre UUID, das erleichtert die Zuordnung.
5. News. Die Beiträge liegen in tl_news mit eigenen Inhaltselementen. Wer nur den News-Bereich braucht, kann seit Contao 5.3 außerdem einen JSON-Feed einrichten, auf Wunsch mit vollständigen Beiträgen statt Anrisstexten. Als Kontrolle ist das nützlich, den Export ersetzt es nicht.
6. Abgleich. Ich vergleiche die Zahl der Seiten, Artikel, Elemente und Beiträge in der Datenbank mit der Zahl im neuen Bestand und liste jede Abweichung.

Beim Datenschutz gilt: Eine Kopie mit Mitgliederdaten oder Formulareinträgen gehört nicht auf eine öffentlich erreichbare Staging-Seite. Zuständig für private Unternehmen in Bayern ist das BayLDA, das auf seiner Startseite unter anderem eine Checkliste für Soloselbstständige und kleine Unternehmen im Handel anbietet. Ich arbeite mit einem Dump ohne diese Tabellen, wenn der Umzug sie nicht braucht.

Foto: Achim Lammerts (Syntaxys), CC BY-SA 4.0, Wikimedia Commons.

#Contao als Headless-Backend behalten oder ersetzen?

Das ist die wichtigste Entscheidung, und sie hängt an Menschen, nicht an Technik. Contao ist laut contao.org als Symfony-Bundle gebaut und läuft weiter, auch wenn das Frontend von Astro oder Next.js kommt. Ich beschreibe beide Wege.

Contao bleibt. Contao liefert von Haus aus nur den News-Feed als JSON. Für Seiten, Artikel und Elemente baue ich in Ihrer Installation einen schreibgeschützten Endpunkt als Symfony-Controller, der die Struktur aus der Datenbank ausgibt. Astro liest ihn beim Build über einen eigenen Loader: Laut Dokumentation lassen sich Inhalte aus beliebigen Quellen laden, und Build-Collections werden zwischen Builds zwischengespeichert. Speichert Ihre Redaktion, löst ein Webhook den neuen Build aus. Das Redaktionsproblem, wie die Vorschau in Hannover aussieht, steht auf der Seite Hannover.

Contao wird abgelöst. Die Inhalte werden zu Markdown oder MDX mit typisierten Feldern, die Seite ist danach ein reines Frontend. Das ist die einfachere Wartung und der richtige Weg, wenn sich die Seite selten ändert, aber es bedeutet, dass Ihre Redaktion die Arbeit am Backend aufgibt. Für die Zeit danach beschreibt Wuppertal die Wartung.

Wenn Sie Datenblätter, Kataloge oder Zertifikate als Downloads führen, wiegt die Dateifrage schwer. In Bayerisch-Schwaben bleibt die Industrie nach einer Prognos-Studie im Auftrag der IHK Schwaben mit 25,9 Prozent der Wertschöpfung eine zentrale Säule (IHK-Startseite, Stand 11.11.2026). Für Betriebe, die so arbeiten, hängt an jedem Download eine UUID, und die Pfade im neuen System müssen stabil sein, weil Kunden und Lieferanten sie oft verlinkt haben. Die Details zu Medien stehen auf der Seite Wien.

#Wie ich die URLs zuordne

Contao baut jede Adresse aus dem Alias der Seite, einem Suffix und optional einem Präfix. Die Einstellungen liegen auf der Startseite einer Website (Seitentyp „Startseite der Website“). Die Doku nennt:

• URL-Suffix. Die Beispiele der Doku enden auf .html. Der Suffix lässt sich ändern oder entfernen.
• URL-Präfix. Er gilt für alle Aliase unterhalb des Einstiegs und ist von der Sprache unabhängig, mehr dazu auf der Seite Basel.
• Ordner-URLs. Sind sie aktiv, steht die Seite „Download“ unter „Docs, Installation“ als docs/install/download.html statt download.html.
• Alias-Zeichensatz. „Über uns“ wird zu ueber-uns oder zu über-uns, je nach Einstellung.
• Startseite. Der Alias index ergibt die leere Anfrage.
• Artikel und News. Ein Artikel hat eine eigene Adresse, etwa company/articles/our-team.html, ein News-Beitrag liegt unter der Leseseite, etwa news/form-follows-function.html. Unbekannte News-Aliase liefern 404.
• Canonical. Contao entfernt Abfrageparameter aus der Canonical-URL, außer Sie tragen sie ein.

Meine Methode: Ich erzeuge die vollständige alte Adressliste nicht aus der Sitemap, sondern aus Contao selbst. Seit 5.3 gibt es dafür den ContentUrlGenerator, der für Seiten und News-Beiträge die echte URL liefert:

$url = $contentUrlGenerator->generate($page, [], UrlGeneratorInterface::ABSOLUTE_URL);

Daneben legt der Seitenbaum Weiterleitungen an: Seitentypen für interne und externe Weiterleitung sind bereits Umleitungen und gehören in die Regelliste. Danach entscheide ich mit Ihnen: Suffix behalten und die meisten Adressen gleich lassen, oder entfernen und jede Adresse einzeln weiterleiten. Wie die 301-Regeln sauber gebaut und geprüft werden, steht auf der Seite Bremen. Titel und Meta-Daten behandelt Mannheim.

#Prüfliste vor dem Start

Wer den Umzug schrittweise machen will, findet das Vorgehen auf der Seite Köln. Die Abnahme vor dem Go-live beschreibt Zürich. Wie ich andere Quellsysteme angehe, steht auf der Seite zur Migration nach Astro und Next.js, etwa bei TYPO3, Joomla und Drupal.

#So läuft ein Auftrag mit mir

Ich bin ein einzelner Entwickler, arbeite von Gdynia aus und ausschließlich schriftlich, ohne Termine und Telefonate.

1. Sie schicken die Adresse, die Contao-Version und Ihr Ziel.
2. Ich lege einen schriftlichen Umfang vor: Seitenzahl, Include-Elemente, Entscheidung Headless oder Ablösung, Suffix, Ausschlüsse und Abnahmekriterien.
3. Ich baue den Export und das Frontend in Branches und zeige Stände auf einer passwortgeschützten Staging-Seite ohne echte Mitgliederdaten.
4. Wir prüfen Seitenzahl, Weiterleitungen, Links und Bilder. Die Core-Web-Vitals-Schwellen stehen auf web.dev: LCP bis 2,5 s, INP bis 200 ms, CLS bis 0,1.
5. Nach Ihrer Freigabe schalte ich um und übergebe den Quellcode.

Das Layout liefern Sie, als Tabellenvorlage oder Figma-Datei. Gestaltung, Mockups und Wireframes gehören nicht zu meinem Angebot, ich setze sie um.

#Fragen aus Contao-Projekten

Hat meine Contao-Version noch Updates? Je nach Version gilt ein anderer Termin: Contao 5.3 bekommt nach dem Release-Plan Fehlerbehebungen bis zum 14. Februar 2027 und danach ein Jahr lang Sicherheitsupdates. Contao 5.7 ist seit dem 15. August 2026 in der Langzeitunterstützung. Stand November 2026.

Muss ich Contao abschalten, wenn die neue Seite online ist? Nein. Contao kann als Redaktionssystem im Hintergrund bleiben, solange es Updates bekommt. Wer es abschaltet, muss die Inhalte an einem neuen Ort pflegen.

Kommen Formulare, Kommentare und Mitgliederbereiche mit? Nicht automatisch. Das sind Include-Elemente, die zur Laufzeit Ausgabe erzeugen. Für jedes brauche ich eine Entscheidung: nachbauen, ersetzen oder entfallen lassen.

Bleiben die URLs mit .html erhalten? Das ist Ihre Entscheidung. Behalten Sie den Suffix, bleiben die meisten Adressen gleich. Lassen Sie ihn weg, braucht jede alte Adresse eine eigene 301-Weiterleitung.

Was passiert mit Bildern und Downloads aus dem Dateimanager? Ich kopiere den Ordner files und löse jede UUID aus den Inhaltselementen in einen neuen Dateipfad auf. Dateien, die nur per FTP hochgeladen und nie synchronisiert wurden, fallen dabei auf.

Was brauche ich von Ihnen für den Start? Die Adresse Ihrer Seite, die Contao-Version, ein Datenbank-Dump einer Kopie, den Ordner files und Ihr Layout als Tabellenvorlage oder Figma-Datei. Das Layout kommt von Ihnen, die Umsetzung von mir.

#Schreiben Sie mir

Schicken Sie mir die Adresse Ihrer Contao-Seite, die Version, Ihr Ziel und einen Wunschtermin, falls es einen gibt. Ich prüfe den Bestand und melde mich schriftlich mit einem Umfang. Die erste Einschätzung ist kostenlos. Am einfachsten geht das über das Kontaktformular. Meine Antwort kommt an Werktagen per E-Mail.