Plattform und Architekturentscheidungen

Plattform und Architekturentscheidungen

0:00 Wer schon einmal eine Erweiterung für Jira oder Confluence gebaut hat, kennt das Gefühl: Man beherrscht React, man weiß, was man bauen will — und trotzdem hakt es an Stellen, die man nicht erwartet hätte. Das liegt selten am Code. Es liegt an zwei Entscheidungen, die ganz am Anfang fallen und danach alles bestimmen: Wo erscheint die App im Produkt, und mit welchem Oberflächenmodell wird sie gebaut.

0:22 Dieses Modul beschäftigt sich ausschließlich mit diesen beiden Fragen. Das klingt nach wenig für einen halben Tag. Aber es ist der Teil, der später am teuersten wird, wenn man ihn überspringt.

Forge verstehen und die erste App starten

0:33 Der erste Tag hat zwei Hälften. In der ersten klären wir, was Forge eigentlich ist und welche Entscheidungen es uns abverlangt. In der zweiten bringen wir eine erste App tatsächlich zum Laufen, in einer eigenen Jira-Instanz. Diese Reihenfolge ist Absicht: Wer erst installiert und dann entscheidet, baut meist an der falschen Stelle.

0:53 Am Ende des Tages haben Sie beides — ein Verständnis der Plattform und eine App, die Sie im Browser sehen können.

Forge-Anwendungen und ihre Bausteine

1:00 Beginnen wir mit der Grundfrage: Was ist eine Forge-App überhaupt? Die Antwort ist überraschend wichtig, weil sie festlegt, welche Gewohnheiten aus der Web-Entwicklung hier tragen — und welche nicht. Stellen Sie sich den Unterschied zwischen einem eigenen Ladengeschäft und einem Stand in einer Markthalle vor. Im eigenen Laden kümmern Sie sich um alles: Miete, Strom, Schloss an der Tür.

1:23 In der Markthalle bekommen Sie eine Fläche, Anschlüsse und Öffnungszeiten — dafür halten Sie sich an die Hausordnung. Forge ist die Markthalle. Ihre App läuft nicht auf Ihrem Server, sondern bei Atlassian. Das Manifest ist der Mietvertrag: Es beschreibt, wo Ihr Stand steht und was Sie dort tun dürfen. Das Frontend rendert direkt in der Atlassian-Oberfläche, die Funktionen laufen serverseitig in der Forge-Laufzeit.

1:47 Diese Schichtung sollten Sie im Kopf behalten, denn fast jede spätere Frage lässt sich damit beantworten. Ganz oben das Produkt, das Ihre App überhaupt anzeigt. Darunter das Frontend, das mit vorgegebenen Komponenten rendert. Darunter die Funktionen, in denen alles läuft, was Sie nicht dem Browser anvertrauen wollen. Und ganz unten die Plattform mit Speicher, APIs und Berechtigungen.

2:10 Wenn später die Frage auftaucht, wo ein Stück Logik hingehört, ist es fast immer die Frage, in welcher dieser Schichten es sitzen soll. Nach oben wird es bequemer, nach unten wird es verlässlicher. Der Gewinn ist real, und er ist größer, als viele erwarten. Sie brauchen keinen Server, kein Deployment-Ziel, keine Zertifikate, die irgendwann ablaufen.

2:31 Authentifizierung und die Trennung zwischen Kunden kommen von der Plattform — zwei Themen, an denen eigene Lösungen regelmäßig scheitern. Berechtigungen stehen als Text im Manifest und nicht verstreut im Code. Dafür zahlen Sie einen Preis: Sie bewegen sich innerhalb von Grenzen, die jemand anderes gesetzt hat. Für die meisten Erweiterungen ist das ein ausgesprochen guter Tausch. Für eine App, die im Kern etwas ganz anderes tut als Jira, eher nicht.

2:59 Diese vier Fehler sehen wir immer wieder, und sie haben alle dieselbe Wurzel: Die App wird geplant wie eine freie Web-Anwendung. Dann fällt erst spät auf, dass das Manifest keine Nebensache ist, sondern festlegt, was überhaupt möglich ist. Oder es wird eine Bibliothek eingeplant, die serverseitig gehört, aber im Frontend landen soll.

3:17 Besonders unangenehm ist der letzte Punkt: Die Betriebskosten der Plattform tauchen erst auf, wenn die App in Benutzung ist — und dann gehört das Gespräch darüber schon jemand anderem.

Erweiterungspunkte in Jira und Confluence

3:28 Kommen wir zur ersten der beiden großen Entscheidungen: Wo genau soll Ihre App im Produkt erscheinen? Das klingt nach einer Frage der Sichtbarkeit. Tatsächlich ist es eine Frage des Kontexts. Ein Modul ist der Andockpunkt Ihrer App an das Produkt. Und hier kommt der Punkt, den man leicht übersieht: Das Modul bestimmt nicht nur, wo etwas zu sehen ist, sondern auch, was Ihre App überhaupt weiß.

3:52 Ein Panel im Vorgang kennt den Vorgang — Nummer, Projekt, Felder. Eine globale Seite in der Navigation kennt ihn nicht, sie ist einfach eine Seite. Wenn Ihre App also etwas über den aktuellen Vorgang sagen soll, ist die Modulwahl bereits getroffen. Umgekehrt gilt das genauso: Wer eine Übersicht über viele Vorgänge braucht, ist im Panel eines einzelnen Vorgangs schlecht aufgehoben.

4:14 Lesen Sie diese Tabelle nicht als Katalog, sondern als Skala. Von oben nach unten wird der Kontext weiter und der Platz größer: Das Panel sitzt eng am Vorgang, die Seitenleiste daneben, die Projektseite umfasst viele Vorgänge, die globale Seite steht für sich. Auf der Confluence-Seite gilt dasselbe Prinzip mit anderen Namen.

4:33 Die praktische Frage lautet deshalb nicht „welches Modul klingt passend", sondern „welchen Kontext braucht meine App, und wie viel Platz braucht ihre Oberfläche". Beides zusammen führt meist eindeutig zu einer Zeile dieser Tabelle. Hier sehen Sie, wie wenig nötig ist, um ein Modul anzumelden — und wie viel in diesen wenigen Zeilen steckt.

4:53 Vier Angaben tragen die Sache: ein Schlüssel, unter dem das Modul ansprechbar ist. Eine Ressource, die auf den Code der Oberfläche zeigt. Die Angabe, dass nativ gerendert wird, also mit UI Kit. Und ein Resolver, der die Backend-Funktion benennt. Merken Sie sich vor allem die Zeile mit dem nativen Rendern: Sie ist die technische Fassung der zweiten großen Entscheidung, über die wir gleich sprechen.

5:17 Steht sie nicht da, erwartet die Plattform etwas völlig anderes. Der häufigste Fehler steht ganz oben: Man wählt die globale Seite, weil sie mehr Platz bietet und nach einer richtigen Anwendung aussieht — und merkt später, dass der Vorgangskontext fehlt, den man eigentlich gebraucht hätte. Das nachträglich zu tauschen, kostet mehr als den Eintrag im Manifest, denn mit dem Kontext fällt auch die halbe Logik weg.

5:40 Und der letzte Punkt ist der leiseste: Ein Panel hat im Entwurf auf dem großen Bildschirm immer mehr Platz als später im echten Vorgang.

UI Kit, Frame oder Custom UI

5:48 Jetzt zur zweiten großen Entscheidung. Sie betrifft die Oberfläche — und sie ist die, bei der Ihre React-Erfahrung Ihnen sowohl hilft als auch im Weg steht. Der Unterschied lässt sich an einer Wohnung erklären. UI Kit ist die möblierte Wohnung: Die Einrichtung ist da, sie passt zum Haus, und Sie ziehen ein. Custom UI ist der Rohbau mit eigenem Eingang — Sie gestalten alles, und Sie kümmern sich auch um alles.

6:13 Frame liegt dazwischen: eine möblierte Wohnung, in der ein Raum frei gestaltbar bleibt. Technisch heißt das: UI Kit rendert React-Komponenten nativ im Produkt, Custom UI läuft in einem iframe mit eigenem HTML, CSS und JavaScript. Und Frame bettet eine begrenzte eigene Fläche in eine UI-Kit-App ein. Diese Gegenüberstellung hat eine Mitte, die man leicht übersieht. Links bekommen Sie das Aussehen des Produkts geschenkt, aber kein DOM.

6:40 Rechts bekommen Sie das volle DOM, aber Sie bauen das Aussehen selbst — inklusive Kontraste, Tastaturbedienung und der Frage, wie das Ganze aussieht, wenn Atlassian sein Design ändert. Die letzte Zeile ist die ehrlichste: schnell fertig gegen mehr Aufbau und Pflege. Und Pflege heißt nicht einmal, sondern bei jeder Änderung, solange die App existiert.

7:02 Der rote Faden dieser fünf Schritte ist eine Zurückhaltung: Beschreiben Sie den fachlichen Bedarf, bevor Sie an die Oberfläche denken. Danach prüfen Sie, ob die mitgelieferten Komponenten diesen Bedarf decken — und das tun sie öfter, als man glaubt, inklusive Tabellen, Diagrammen und Formularen. Erst wenn einzelne Sonderfälle übrig bleiben, kommt Frame ins Spiel. Und erst wenn DOM-Zugriff wirklich unverzichtbar ist, Custom UI.

7:27 Der letzte Schritt ist kein Formalismus: Schreiben Sie die Entscheidung auf. In einem halben Jahr fragt jemand, warum das so gebaut wurde — und dann zählt die Begründung, nicht die Erinnerung. Hier lohnt der erste Punkt eine Einordnung. Custom UI wird sehr oft aus Gewohnheit gewählt: Es fühlt sich an wie normale Web-Entwicklung, und das ist angenehm.

7:48 Der Preis zeigt sich erst später, wenn die App neben dem Produkt fremd wirkt und jede Design-Änderung nachgezogen werden muss. Der zweite Punkt ist der umgekehrte Fehler, und er ist teurer: UI Kit gewählt, obwohl eine DOM-abhängige Bibliothek von Anfang an feststand. Und der dritte ist der eigentliche Klassiker — entschieden wird, bevor überhaupt klar ist, was die App tun soll.

Grenzen des nativen Renderings

8:10 Damit die Entscheidung für UI Kit eine informierte bleibt, schauen wir uns jetzt genau an, was „nativ rendern" bedeutet — und was dabei wegfällt. Das ist die Stelle, an der erfahrene React-Entwickler kurz stutzen. UI Kit nutzt React, aber nicht React DOM. Das klingt nach einer Feinheit und ist es nicht: Es gibt keine HTML-Elemente, keine Portale, kein Weiterreichen von Refs auf DOM-Knoten und kein document.

8:36 Die Hooks, die Sie kennen, funktionieren — useState, useEffect, useContext, useReducer und die üblichen weiteren. Was nicht funktioniert, ist alles, was am Ende doch ein Element im Browser anfassen will. Anders gesagt: Ihr React-Wissen trägt, Ihr Browser-Wissen nur eingeschränkt. Der Vergleich auf dieser Folie ist bewusst banal gewählt, weil genau solche Banalitäten am Anfang stolpern lassen.

9:01 Oben der Reflex: ein div mit einer Klasse, und wenn es sein muss, ein Zugriff auf das Element. Beides existiert hier nicht. Unten dieselbe Ausgabe mit den Mitteln der Plattform: eine Layout-Komponente für die Anordnung, eine Text-Komponente für den Inhalt, eine Status-Komponente für den Zustand. Worauf es ankommt: Sie beschreiben nicht mehr, wie etwas aussehen soll, sondern was es ist. Das Aussehen liefert das Produkt — und zwar in jeder Instanz konsistent.

9:29 Diese vier Punkte sind der Preis, und er gehört offen benannt. Fertige Komponentenbibliotheken fallen weg — kein Chart-Paket aus dem Web, kein Editor-Widget. Messungen am gerenderten Element sind nicht möglich, weil es das Element nicht gibt. Animationen und Fokus-Tricks über das DOM ebenso. Und der praktisch wichtigste Punkt: Testwerkzeuge, die das gerenderte DOM untersuchen, greifen an dieser Oberfläche nicht — worauf wir am vierten Tag noch einmal ausführlich zurückkommen, wenn es ums Testen geht.

9:59 Der erste Punkt ist der tückischste, weil er zeitverzögert zuschlägt: Ein Hook aus einer Bibliothek greift irgendwo tief innen auf window zu. Das sieht man dem Import nicht an, und es fällt erst zur Laufzeit auf. Der dritte Punkt ist der, der Sie im Alltag am häufigsten treffen wird: Sie finden ein Beispiel, das funktioniert — aber es stammt aus einer Custom-UI-App, wo HTML selbstverständlich ist.

10:22 Prüfen Sie bei jedem gefundenen Beispiel zuerst, aus welcher Welt es kommt.

Übung

10:27 Genug Theorie. Zeit, die beiden Entscheidungen an einem konkreten Fall selbst zu treffen — und, was wichtiger ist, sie zu begründen. Unser Beispiel begleitet uns durch das ganze Seminar. Die Falkenmoos GmbH entwickelt Laborsoftware. Entscheidungen zu laufenden Projekten werden heute in Jira-Kommentaren festgehalten — und sind nach zwei Wochen faktisch verschwunden.

10:50 Jeder kennt dieses Problem in irgendeiner Form. Die geplante App Klarpfad soll offene Entscheidungen am Vorgang sichtbar machen, ihre Erfassung erlauben und den Status pflegen. Klein genug, um es in fünf Tagen fertig zu bekommen. Und groß genug, um unterwegs auf alle Fragen zu stoßen, die eine echte App auch stellt. Es geht in dieser Aufgabe ausdrücklich nicht um Code.

11:12 Es geht um den Steckbrief: Anwendungsfall, Modul, UI-Modell — und je ein Grund, warum die beiden anderen UI-Modelle ausscheiden. Diese letzte Anforderung ist die eigentliche Übung. Eine Entscheidung zu treffen, ist leicht; zu sagen, was man damit verwirft, ist die Arbeit. Wer früh fertig ist, schaut zusätzlich voraus: Welcher Teil dieser Lösung wäre auch als Confluence-Erweiterung sinnvoll? Diese Frage begleitet uns bis zum letzten Tag.

11:40 Der Ablauf spiegelt genau die Reihenfolge, über die wir gesprochen haben. Erst der Anwendungsfall in drei Sätzen ohne Technik — wer das nicht hinbekommt, hat meist noch kein Problem, sondern eine Lösung gesucht. Dann der Kontext: Was muss die App wissen, um nützlich zu sein? Daraus folgt das Modul fast von selbst. Danach halten Sie den Oberflächenbedarf gegen die vorhandenen Komponenten.

12:03 Und am Ende steht eine Seite Papier. Eine Seite reicht — mehr liest später ohnehin niemand. Zum Schluss drei Muster, die Sie in der eigenen Arbeit wiedererkennen werden. Der Steckbrief beschreibt die Oberfläche statt den Anwendungsfall — verständlich, weil die Oberfläche konkreter ist, aber es verschiebt die Entscheidung an die falsche Stelle.

12:23 Das Modul wird nach Sichtbarkeit gewählt statt nach Kontext. Und die Begründung nennt nur die gewählte Option. Behalten Sie das im Kopf: Eine Begründung ohne verworfene Alternativen ist keine Begründung, sondern eine Beschreibung. Im nächsten Modul bringen wir diese Entscheidungen dann zum Laufen.