Richtlinien für Entwicklung

Dieser Abschnitt richtet sich an Entwickler:innen, die am Projekt mitarbeiten oder neue Funktionen ergänzen möchten.

Allgemeine Prinzipien

Klarheit vor Cleverness
Serverlogik und Clientlogik trennen
Navigation und Layout konsequent über Metadaten steuern
Hooks nur in Client Komponenten verwenden
SSR und Hydration im Blick behalten

Das Ziel ist, dass neue Funktionen sich nahtlos in die bestehende Architektur einfügen.

Arbeiten mit tanstack Router

Neue Seiten werden über Dateien unter apps/web/src/routes angelegt.
createFileRoute wird verwendet, um Komponente, Loader und Guards zu definieren.

Nach Änderungen generiert tanstack Router die Datei routeTree.gen.ts neu, sodass Typsicherheit für to Werte in Links und Redirects gegeben ist.

Beim Redirect auf dynamische Pfade sollte nach Möglichkeit auf bekannte Routen-IDs oder auf registrierte Pfade verwiesen werden, da Tanstack Router zur Compilezeit eine Union aller erlaubten Strings erzeugt.

Authentifizierung und Organisationen

Der Auth Client wird in apps/web/src/lib/auth-client.ts erzeugt.
Er enthält Hooks wie:

useSession zur Abfrage der angemeldeten Person
useListOrganizations zur Liste von Organisationen
useActiveOrganization zur aktiven Organisation und deren Metadaten

Beim Teamwechsel wird authClient.organization.setActive verwendet.
Anschließend beziehen NavMain und andere Komponenten ihre Daten aus der aktualisierten Organisation.

Navigation über Metadaten

Navigation gehört in die Metadaten und nicht in hart codierte Komponenten.
Das erleichtert spätere Änderungen und erlaubt unterschiedliche Menüs je Organisation.

parseNavigationGroups unterstützt die Umwandlung der rohen JSON Struktur in typsichere Objekte, die dann von NavMain dargestellt werden.

Beim Hinzufügen neuer Felder (zum Beispiel external) sollte der Parser entsprechend erweitert werden.

Skeletons und Ladezustände

Ladezustände sollten visuell konsistent umgesetzt werden.
Die Komponente Skeleton aus apps/web/src/components/ui/skeleton.tsx wird genutzt, um Platzhalter in Navigation und TeamSwitcher anzuzeigen.

Wichtig:
Vom Server sollte die gleiche Struktur gerendert werden, die der Client später hydratisiert.
Deshalb empfiehlt sich die Kombination aus Loadern, die initiale Daten liefern, und Hooks, die Aktualisierungen im laufenden Betrieb abbilden.