Luminary: Warum wir Next.js für die Migration nutzten und was wir lernten

Die Plattform Luminary feierte Frauen, die in unterschiedlichsten Bereichen wie Technologie, Wissenschaft oder Kunst gesellschaftlichen Wandel vorantreiben. Nach einer vierwöchigen Entwicklungsphase für den grundlegenden Aufbau der Community-Plattform mit reinem HTML, CSS und JavaScript begann das Team eine systematische Modernisierung. Der Umstieg auf eine moderne Architektur sollte langfristig Wartbarkeit und Skalierbarkeit sicherstellen – und das gelang mit Next.js, Turborepo und einem durchdachten Designsystem.

Die Motivation hinter der Migration

Das ursprüngliche Luminary bestand aus isolierten HTML-Seiten, die mit individuellen Skripten und Stylesheets verbunden waren. Diese Lösung funktionierte zwar, doch mit dem Wachstum des Projekts wurde die gemeinsame Nutzung von Logik, die Konsistenz der Styles und die Integration mit dem Backend zunehmend komplexer. Die Entscheidung fiel daher auf eine vollständige Neugestaltung der Architektur.

In einem zweitägigen Sprint wurde das Projekt in ein Turborepo-Monorepo überführt, das zwei Anwendungen umfasst: ein Next.js-Frontend mit App Router und TypeScript sowie ein Backend auf Basis von Express und Supabase. Die Frontend-Komponenten wurden mit Tailwind für das Styling, Base UI für barrierefreie UI-Primitiven, TanStack Query für die Datenabfragen und einem gemeinsamen Designsystem realisiert.

Meine Hauptaufgabe bestand darin, den Nominierungsprozess sowie die Verzeichnis- und Profilseiten zu migrieren. Die Arbeit wurde über Feature-Branches koordiniert, wobei jedes Teammitglied die Seiten übernahm, die es ursprünglich entwickelt hatte.

Woche 1: Migration der Nominierungsfunktionen

Die erste Woche konzentrierte sich auf die Umstellung des Nominierungsprozesses von einem DOM-gesteuerten Formular zu einer React-basierten Lösung in Next.js. Der Fokus lag auf der Erstellung wiederverwendbarer Komponenten und der Integration eines robusten Datenabfrage- und Servicesystems.

Kernfunktionen im Überblick

• Neugestaltung des Nominierungs- und Selbst-Einreichungsformulars als kompositionelle React-Komponenten
• Erweiterung der gemeinsamen Formular-Komponentenbibliothek, sodass alle Eingabefelder eine zentrale Datenquelle nutzen
• Anbindung der Formulare an TanStack Query und eine typisierte Service-Schicht

Technische Umsetzung im Detail

• Gemeinsame Formular-Primitiven: Die bestehende form-Komponente wurde zu FormField, TextField, FormLabel und einem SelectField auf Basis von Base UI erweitert. Dadurch sind Labels und Eingabefelder zentral definiert und werden überall wiederverwendet.

• Datenauslagerung aus Komponenten: Formularkonstanten wie der initiale Zustand, Tabs und Feldoptionen wurden in die Datenebene verschoben. Die Komponenten konzentrieren sich nun auf die Darstellung.

• Designsystem-Konsistenz: Rohes HTML (<button>, <a>) wurde durch das einheitliche Button-Komponentensystem ersetzt. Auch kollabierbare Abschnitte erhielten eine wiederverwendbare Drawer-Wrapper-Komponente auf Basis von Base UI.

• Service-Schicht: Die Logik wurde in NominationService und UploadService aufgeteilt. Eine private Methode toPayload sowie ein gemeinsames Fehler-Handling-System sorgen für konsistente API-Nachrichten.

• Submissions-Workflow: Statt manueller try/catch-Blöcke wurde nun TanStack Query’s Mutation-Feature mit onError-Handler genutzt. API-Fehler wurden in eine typisierte Antwortstruktur überführt.

Herausforderungen und Lösungen

• Imperativen Code in Komponenten umwandeln: Das ursprüngliche Formular nutzte direkte DOM-Manipulation. Die Umstellung erforderte ein Umdenken hin zu kompositionellen React-Komponenten, bei dem gemeinsame Elemente wie Labels, Eingaben und Schaltflächen als wiederverwendbare Primitiven neu strukturiert wurden.

• Feedback aus Code-Reviews umsetzen: Ein großer Teil der Woche wurde für die Beantwortung von Pull-Request-Reviews aufgewendet. Isaac, der Hauptverantwortliche für das Repository, wies auf die Notwendigkeit hin, die Konventionen des Teams streng einzuhalten – etwa die Verwendung der Designsystem-Komponenten, die Entfernung überflüssiger Memoisierungen (da der React-Compiler genutzt wird) und die Verlagerung wiederholter Logik in gemeinsame Hilfsfunktionen.

Erkenntnisse aus Woche 1

Die Migration der Nominierungsfunktionen brachte wertvolle Einblicke in eine komponentengetriebene, design-system-first-Entwicklungsweise. Besonders die Modellierung von Datenabfragen und Submissions mit TanStack Query sowie die Strukturierung einer typisierten Service-Schicht in TypeScript erwiesen sich als wertvolle Best Practices für zukünftige Projekte.

Woche 2: Migration der Verzeichnis- und Profilseiten

In der zweiten Woche verlagerte sich der Fokus von Formularen auf die Datenebene. Ziel war es, die Verzeichnis- und Profilseiten mit echten Backend-Daten zu verbinden und die letzten verbleibenden Seiten aus dem alten Projekt zu portieren.

Kernfunktionen im Überblick

• Migration der alten Profilseite aus dem HTML/JS-Projekt in eine Next.js-Dynamische-Route mit Live-Daten
• Implementierung einer gemeinsamen Mapping-Schicht zwischen API und UI-Profilstruktur

Technische Umsetzung im Detail

• Profil-Route: Die Route /directory/[id] wurde als asynchrone Serverkomponente angelegt. Die ursprünglichen Abschnitte der profile.html (Header, Über mich, verwandte Links) wurden als Komponenten neu aufgebaut, wobei next/image für die Bilddarstellung und der ursprüngliche dekorative Bilderrahmen verwendet wurden.

• Gemeinsamer Mapper: Eine zentrale toNomineeProfile-Funktion wurde eingeführt, die sowohl die Verzeichnisliste als auch die neue getProfileById-Methode speist. Dadurch wurden inkonsistente URL-Felder aus der API normalisiert.

• Bildkonfiguration: Remote-Bildquellen wurden in der Next.js-Konfiguration zugelassen, sodass Profil- und Avatarbilder über die Next.js-Bildpipeline gerendert werden konnten.

Herausforderungen und Lösungen

• „Not Found“-Fehler bei Profilen: Die Verzeichniskarten nutzten die Nominee-ID als Schlüssel, während die Detailseite über die Nominierungs-ID arbeitete. Durch den gemeinsamen Mapper wurden beide IDs angeglichen.

• Backend startet nicht lokal: Die fehlende Umgebungsdatei verhinderte den Start des Backends. Nach deren Ergänzung warf der Supabase-Client weiterhin Fehler aus, da Node.js-Versionen unter 22 keine native WebSocket-Unterstützung bieten. Ein ws-Fallback wurde hinzugefügt, um dieses Problem zu umgehen.

• Black Hole bei Anfragen: Trotz laufendem Server erreichten Anfragen diesen nicht, da Port 5000 systemweit reserviert war. Die Umstellung auf einen freien Port löste das Problem sofort.

Fazit: Lessons Learned und Ausblick

Die Migration von Luminary zu Next.js und Turborepo hat nicht nur die technische Grundlage für zukünftiges Wachstum gelegt, sondern auch wertvolle Erkenntnisse für die Zusammenarbeit im Team geliefert. Die komponentengetriebene Architektur, die Integration eines Designsystems und die strukturierte Datenabfrage mit TanStack Query haben die Entwicklungsgeschwindigkeit erhöht und die Codequalität spürbar verbessert.

Das Projekt zeigt, wie wichtig es ist, frühzeitig auf modulare Architekturen zu setzen und gemeinsame Standards für Design und Datenfluss zu etablieren. Die nächsten Schritte werden sich auf die weitere Optimierung der Performance, die Erweiterung der Barrierefreiheit und die Integration zusätzlicher Funktionen konzentrieren – immer mit dem Ziel, eine noch inklusivere und leistungsfähigere Plattform für die Community zu schaffen.