Module (NXM)

Entwickeln, Fehler finden, testen

Wie Sie ein NXM-Modul mit der VS-Code-Erweiterung von nexxus oder der Kommandozeile nxm bauen. Probleme erscheinen beim Speichern, jede Änderung läuft gleich darauf in einem Testmandanten, Dienste laufen unter dem Debugger, und ein Protokoll je Installation zeigt, was passiert ist.

Für: Entwickler
Dauer: 15 Min.

Ein Modul zu bauen soll sich anfühlen wie eine Web-App zu bauen: Sie speichern eine Datei und sehen die Änderung einen Moment später, in einem echten nexxus mit Ihren Beispieldaten. Geht etwas schief, lesen Sie den Grund in einem Protokoll, statt zu raten. Und bevor Sie ein Paket weitergeben, wissen Sie schon, ob nexxus es annimmt.

Dafür gibt es die Erweiterung nexxus Module für Visual Studio Code. Sie prüft Ihr Paket beim Speichern, installiert es in einem Testmandanten und hält es dort mit jedem Speichern auf dem Stand. Die Regeln kennt sie nicht selbst: Jedes Paket geht an die Instanz, die dieselben Prüfungen ausführt wie beim Hochladen. Ohne VS Code, und für Coding-Agenten, tut die Kommandozeile nxm dasselbe.

Paket anlegen
Ein Paket, das sich so, wie es ist, installieren lässt: Manifest, Ansicht, Beispieldaten.
Verbinden
Mit einer Instanz und Ihrem persönlichen API-Token.
Dev-Modus
Jedes Speichern wird im Testmandanten installiert, die offene Ansicht lädt neu.
Debuggen
Haltepunkte in Ihren Diensten und Ansichten, wie in jedem Web-Projekt.
Protokoll
Dienstaufrufe, Migrationen und Fehler der Ansichten, live und mit Wiederholen.

Der Entwicklungskreislauf mit der VS-Code-Erweiterung.

Was Sie brauchen

Visual Studio Code 1.90 oder neuer.
Die Erweiterung als Datei nexxus-modules.vsix. Sie steht nicht im Marketplace. Sie bekommen sie von Ihrem Ansprechpartner bei Systaro; mit Zugang zum GitLab von nexxus laden Sie die neueste hier. Installieren Sie sie in VS Code über die Ansicht Extensions, Menü ..., Install from VSIX…, oder auf der Kommandozeile mit code --install-extension nexxus-modules.vsix. Eine neuere Datei installieren Sie genauso über die alte.
Eine Instanz mit Testmandanten. Ein nexxus, das Sie aus den Quellen mit dem Spring-Profil development oder local starten, hat sie von selbst. Auf einer anderen Instanz schaltet ihr Betreiber sie ein, mit nexxus.modules.scratch.enabled und nexxus.modules.scratch.domain-template, dem Host je Testmandant (etwa {slug}.module.example.com, mit DNS und Zertifikat für diese Hosts).
Ein Administratorkonto auf dieser Instanz und dazu ein persönliches API-Token.
Deno 2, nur wenn Ihr Paket eigene Dienste hat (Installation).

Ein Paket anlegen

Öffnen Sie einen leeren Ordner und klicken Sie in der Aktivitätsleiste auf den Würfel nexxus Module. Die Seitenleiste bietet Neues Paket anlegen an. Der Befehl fragt nach dem Schlüssel (acme.aufgaben: Herausgeber und Name, kleingeschrieben) und dem Namen in der App und schreibt:

Ordneracme.aufgaben/
- Ordner1.0.0/
  - module.json ein Fachobjekt mit Liste und Datensatzansicht, eine eigene Seite, eine Aktion
  - CHANGELOG.md
  - Ordnerui/
    offen.html
  - Ordnerdemo/ Beispieldatensätze
    …

Das Paket lässt sich so, wie es ist, installieren. Danach bietet die Erweiterung an, den Dev-Modus darauf zu starten. Die Dateien sind gewöhnliche Dateien: Sie bearbeiten sie im Explorer, die Erweiterung prüft und installiert sie beim Speichern. Wie die Teile zusammenspielen, zeigt Ihr erstes Modul.

Mit einer Instanz verbinden

Legen Sie in der App ein API-Token an, wie in Persönliche API-Tokens beschrieben. Das Konto muss Administrator des Mandanten sein: Prüfen und Hochladen ist dasselbe Recht wie das Hochladen in der App.
Führen Sie in VS Code den Befehl nexxus: Mit Instanz verbinden aus. Geben Sie die Adresse an, unter der die API antwortet, etwa https://nexxus.example.com, und fügen Sie das Token ein (cx_...).

Die Adresse muss mit https beginnen. Nur localhost, 127.0.0.1 und [::1] gehen auch mit http, weil jeder Aufruf das Token eines Administrators trägt. Die Erweiterung prüft das Token, bevor sie es behält, und legt es nur im Schlüsselbund Ihres Betriebssystems ab, nie in Einstellungen oder Dateien. Die Statusleiste zeigt die Instanz; ein Klick darauf verbindet neu oder trennt.

Probleme beim Speichern

Verfügbar

Jede module.json prüft die Erweiterung schon beim Tippen gegen das JSON-Schema von nexxus, auch ohne Verbindung: Vervollständigung der Felder, ihre Typen, und ein vertipptes entitys oder eine Version 1.0 sind unterstrichen.

Mit Verbindung schickt die Erweiterung bei jedem Speichern das ganze Paket an die Instanz (POST /api/module-packages/validate). Die Instanz prüft es wie beim Hochladen und, wenn der Mandant das Paket installiert hat, zusätzlich nach den Regeln einer Aktualisierung gegen die installierte Version. Sie speichert dabei nichts. Jedes Problem erscheint im Fenster Problems an seiner Stelle:

in module.json und in den Dateien unter demo/ an dem JSON-Pfad, den die Prüfung nennt, oder am nächsten vorhandenen darüber, wenn eine Eigenschaft fehlt,
in der ersten Zeile seiner Datei, wenn es keinen Pfad hat (CHANGELOG.md, Vorlagen),
in der ersten Zeile von module.json, wenn es keine Datei hat.

Ist ein Problem behoben, verschwindet es beim nächsten Speichern.

Das Schema liegt den nexxus-Quellen bei, als backend/src/main/resources/modules/module-runtime/module-package.schema.json. Kopieren Sie es neben Ihre Pakete und sagen Sie VS Code in .vscode/settings.json, dass es für jede module.json gilt:

{
  "json.schemas": [
    { "fileMatch": ["**/module.json"], "url": "./module-package.schema.json" }
  ]
}

Der Dev-Modus: Änderungen beim Speichern sichtbar

Verfügbar

Testmandanten

Der Dev-Modus arbeitet in einem Testmandanten: einem eigenen Mandanten auf der Instanz, leer bis auf einen Administrator, der für Sie steht. Was Sie dort tun, berührt keinen anderen Mandanten. Ein Testmandant läuft nach 7 Tagen ab, Sie können ihn bis 30 Tage nach dem Anlegen verlängern, und jede Person hat höchstens 5. Ist er abgelaufen, löscht die Instanz ihn innerhalb einer Stunde mit seinen Paketen und Daten. In der App steht oben eine schmale Leiste wie Testmandant „Aufgaben“ · läuft ab am 02.11.2026.

Die Seitenleiste zeigt Ihre Testmandanten unter Testmandanten, mit dem Ablaufdatum. Über die Knöpfe oder das Kontextmenü legen Sie einen an (Testmandant anlegen), öffnen ihn im Browser, schon angemeldet (Testmandant im Browser öffnen), verlängern oder löschen ihn, und mit Für den Dev-Modus verwenden nimmt der Dev-Modus ihn ohne Nachfrage.

Den Dev-Modus starten

Starten Sie ihn am Versionsordner in der Seitenleiste (Blitz-Symbol), im Kontextmenü einer Datei des Ordners, über den Eintrag Dev-Modus in der Statusleiste oder mit nexxus: Dev-Modus starten. Beim ersten Mal fragt die Erweiterung, welchen Testmandanten sie nehmen soll, oder legt einen an. Dann:

Sie packt den Ordner im Speicher als Entwicklungsversion, etwa 1.2.0-dev. Ihre module.json auf der Platte bleibt, wie sie ist; dort steht weiter 1.2.0.
Beim ersten Mal installiert die Instanz das Paket mit seinen Beispieldaten und gibt Ihnen jede Rolle des Pakets, ohne Dialog.
Danach installiert die Erweiterung bei jedem Speichern einer Datei im Ordner neu, kurz nach dem letzten Speichern. Die Instanz wendet die Version an wie eine Aktualisierung: Ihre Datensätze bleiben, und Migrationsschritte, die noch nicht gelaufen sind, laufen. Eine kaputte Migration fällt also bei dem Speichern auf, das sie kaputt gemacht hat.
Offene Ansichten des Moduls laden an Ort und Stelle neu, auf derselben Seite.

Die Statusleiste zeigt, während eine Installation läuft, ein Drehsymbol und danach ihre Dauer. Probleme des Pakets erscheinen im Fenster Problems wie oben. Ein Klick auf den Eintrag öffnet sein Menü: den Testmandanten im Browser, das Protokoll, eine Aktion durchspielen, einen Dienst oder die Ansichten debuggen, die Daten zurücksetzen oder den Dev-Modus beenden.

Eine Entwicklungsversion braucht keine eigene Überschrift in der CHANGELOG.md: ## [1.2.0] gilt auch für 1.2.0-dev. Migrationsschritte schreiben Sie wie immer unter die Release-Version ("1.2.0"). Eine veröffentlichte Version bleibt fest wie bisher: Dieselbe Version mit anderem Inhalt lehnt nexxus ab. Nur eine Entwicklungsversion nimmt neuen Inhalt an, und eine installierte nur über den Dev-Modus.

Wenn die Instanz einen Schritt ablehnt

Manches lässt nexxus bei einer Aktualisierung nicht zu, etwa eine Änderung, bei der Daten verloren gingen, die der Testmandant schon hat. Die Erweiterung zeigt dann den Grund. Wo es hilft, bietet sie Daten zurücksetzen an: Das Paket wird mit seinen Daten entfernt und mit den Beispieldaten neu installiert; die übrigen Daten des Testmandanten bleiben. Denselben Knopf hat die Paketseite in der App, nur in Testmandanten.

Dienste auf Ihrem Rechner

Verfügbar

Bringt Ihr Paket eigene Dienste mit (services in module.json), liegt ihr Code im Versionsordner unter services/<dienst>/main.ts. Dieser Ordner kommt nicht mit ins Paket. nexxus: Dienst anlegen schreibt den Anfang für einen Dienst, den das Manifest nennt: main.ts mit einem Ereignis-Handler und einer Aktion, und eine deno.json, die @nexxus/module-kit auf das Service-Kit zeigt. Das Kit legt die Erweiterung unter .nexxus/kit/ in Ihren Arbeitsordner, mit einer eigenen .gitignore.

Im Dev-Modus läuft jeder Dienst auf Ihrem Rechner, mit deno serve --watch --inspect und PLATFORM_URL auf die Instanz gesetzt. Deno startet ihn bei jeder Änderung seiner Dateien neu. Die Instanz erreicht ihn über einen Tunnel, den die Erweiterung offen hält: Aufrufe des Testmandanten an die Adresse des Dienstes gehen an Ihren Rechner, ohne dass Sie eine Adresse freigeben oder einer neuen zustimmen müssen. Jeder Dienst schreibt in einen eigenen Ausgabekanal nexxus Dienst: acme.aufgaben/fristen, eine Zeile je Aufruf mit Status, Dauer und Aufruf-ID.

Das Kit beantwortet /<name>/events und /<name>/actions/<operation>, mit dem Namen, den main.ts dem Kit gibt. Die Adresse des Dienstes in module.json endet deshalb auf diesen Namen, etwa http://localhost:8390/fristendienst.

Läuft der Dev-Modus nicht, scheitert ein Aufruf sofort, und das Protokoll sagt Der lokale Dienst ist nicht verbunden. Starte den Dev-Modus in VS Code. Ereignisse warten so lange; sobald der Tunnel offen ist, stellt die Instanz sie innerhalb weniger Sekunden zu.

Debuggen

Verfügbar

Die Erweiterung bringt den Debug-Typ nexxus mit. Er startet den Dev-Modus, wenn er noch nicht läuft, und übergibt an den JavaScript-Debugger von VS Code:

Einen Dienst: Drücken Sie F5 in einer Datei unter services/<dienst>/. Der Debugger hängt sich an den Dienst und nach jedem Neustart durch --watch wieder an. Haltepunkte in main.ts halten.
Die Ansichten: F5 in einer Datei unter ui/ öffnet Chrome im Testmandanten, schon angemeldet. Haltepunkte in ui/*.html halten.

Mit einer .vscode/launch.json legen Sie beides fest:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "nexxus",
      "request": "attach",
      "name": "Fristen debuggen",
      "folder": "${workspaceFolder}/acme.aufgaben/1.2.0",
      "service": "fristen"
    },
    {
      "type": "nexxus",
      "request": "launch",
      "name": "Ansichten debuggen",
      "folder": "${workspaceFolder}/acme.aufgaben/1.2.0"
    }
  ]
}

In den Entwicklerwerkzeugen des Browsers

Eine Ansicht läuft in einem abgeschotteten Rahmen innerhalb der Seite, die Entwicklerwerkzeuge des Browsers funktionieren also wie gewohnt. Ihre Skripte erscheinen dort unter dem Dateinamen der Ansicht, etwa ui/offen.html, mit denselben Zeilennummern wie im Editor. Was die Ansicht mit console.log oder console.error schreibt, und Fehler, die sie nicht abfängt, stehen in der Konsole der Seite. Die Adresse des Rahmens ist about:srcdoc, sein Ursprung null: Um Befehle im Dokument der Ansicht auszuführen, wählen Sie diesen Rahmen als Kontext der Konsole. Ein fetch an Ihren eigenen Server scheitert mit Absicht, weil die Sandbox kein Netzwerk erlaubt; nehmen Sie stattdessen nx.records und die anderen Aufrufe des SDK. Wie Ansicht und nexxus miteinander sprechen, steht in Das Protokoll, zur Fehlersuche.

Sehen, was passiert ist: das Protokoll

Verfügbar

Jede Installation hat ein Protokoll. Sie finden es auf ihrer Paketseite unter AdministrationBetriebModule, Reiter Pakete, im Reiter Protokoll, und in VS Code mit nexxus: Protokoll in einem Fenster neben dem Editor. Beide zeigen neue Einträge, sobald sie entstehen, und lassen sich nach Art und Stufe filtern. Das Protokoll enthält, mit Zeitpunkt und Ergebnis:

Installation, Aktualisierung, Zurücksetzen, Aktivieren, Deaktivieren und Entfernen, und jeden Migrationsschritt, der lief,
Uploads und Installationen im Dev-Modus, die nexxus abgelehnt hat, mit jedem gefundenen Problem,
jeden Aufruf eines Dienstes: Aktion, Ereigniszustellung, Endpunkt des Kundenportals, mit Status, Dauer, dem Fehler und einer Aufruf-ID, die auch der Dienst bekommt (X-Nexxus-Correlation-Id), damit Sie denselben Aufruf in der Ausgabe Ihres Dienstes finden,
nur bei Entwicklungsversionen: die gesendete Anfrage und die Antwort jedes Dienstaufrufs, jede deklarative Aktion, die lief, mit ihren ausgewerteten Werten, und was Ihre Ansichten mit console.error schreiben oder nicht abfangen.

Einträge, die einen Dienstaufruf einer Entwicklungsversion aufgezeichnet haben, schickt Erneut senden noch einmal an den Dienst, im Dev-Modus also an den auf Ihrem Rechner: Haltepunkt setzen, erneut senden, Schritt für Schritt durchgehen. Der neue Aufruf erscheint als eigener Eintrag.

Das Protokoll reicht 30 Tage zurück. Auch der KI-Assistent kann es für Administratoren lesen, etwa wenn Sie ihn fragen, warum eine Zustellung fehlschlägt.

Eine Aktion durchspielen

Verfügbar

nexxus: Aktion durchspielen fragt nach einer Aktion des Pakets, einem Datensatz und den Eingaben, die die Aktion liest. Dann fragt die Erweiterung die Instanz, was die Aktion tun würde. Nichts läuft, nichts wird geschrieben. Das Fenster zeigt, ob sie laufen würde und was sie bewirken würde, ob Sie das Recht dazu haben, jede Bedingung aus when mit dem Wert im Datensatz und jede Vorlage wie {{record.titel}} mit dem Wert, der herauskommt. Erneut durchspielen fragt mit denselben Eingaben noch einmal, etwa nach einem Speichern. Hat die Instanz das letzte Speichern abgelehnt, spielt sie den zuletzt installierten Stand durch, und das Fenster sagt es.

Testen

Dienste Verfügbar. Das Service-Kit bringt eine nachgebildete Plattform für Tests mit: FakePlatform.start() stellt die Schlüssel bereit, signiert Aufruf-Tokens wie nexxus, führt den Token-Tausch aus und hält Datensätze im Speicher hinter der Datensatz-API. seed(module, entity, data) legt Datensätze an, list(module, entity) liest sie zurück, stop() beendet sie. Sie liegt in den nexxus-Quellen unter module-services/src/kit/testing/; die Tests des Fristendiensts nutzen sie, in module-services/src/fristendienst/service.test.ts. Sie laufen mit bun test. Die Kopie des Kits, die die Erweiterung schreibt, enthält sie nicht.

Ansichten Geplant. Ein nachgebildeter Host steht für nexxus, sodass sich eine Ansicht mit Vitest testen lässt: Sie geben ihr Datensätze und Kontext, die Ansicht läuft, und Sie prüfen, was sie aufgerufen und angezeigt hat. Bis dahin testen Sie Ansichten im Dev-Modus.

Hochladen

nexxus: Hochladen baut das Paket, lädt es auf die verbundene Instanz und öffnet seine Paketseite. Installieren tut der Befehl nie: Das macht ein Administrator auf dieser Seite, wo er Rollen wählt und zustimmt. Hochgeladen wird die Version, die in module.json steht, nie die Entwicklungsversion des Dev-Modus. nexxus: Paket bauen legt die Datei nur ab, als dist/<key>-<version>.nxm im Arbeitsordner.

Die Erweiterung baut unsignierte Pakete. Außerhalb der Profile development, local und demo nimmt eine Instanz sie nur an, wenn ein Administrator des Mandanten auf dem Reiter Herausgeber den Schalter Unsignierte Pakete zulassen eingeschaltet hat. Ein signiertes Paket bauen Sie auf der Kommandozeile, siehe Dem Herausgeber vertrauen.

Auf der Kommandozeile und in CI

Ohne die Quellen von nexxus nehmen Sie nxm validate und nxm build (oben), mit gesetztem NXM_URL und NXM_TOKEN. Haben Sie die Quellen, prüft die Gradle-Aufgabe validatePackage einen Paketordner so, wie nexxus es tut: Schema, alle Regeln, die Vorlagen und die Datendateien. Rufen Sie sie in backend/ auf:

./gradlew validatePackage -Pdir=/pfad/zu/acme.besucher/1.1.0   # ein Versionsordner
./gradlew validatePackage -Pdir=/pfad/zu/acme.besucher         # alle Versionen eines Pakets
./gradlew validatePackage -Pdir=/pfad/zu/acme.besucher/package -Pprevious=/pfad/zur/letzten-version

Ein Ordner, der wie eine Version heißt, muss in <key>/<version> liegen; ein Ordner mit anderem Namen hält die aktuelle Version eines Pakets, etwa in einem eigenen Repository, das Versionen als Git-Tags veröffentlicht. -Pprevious vergleicht mit der letzten Version und prüft die Regeln einer Aktualisierung: eine höhere Versionsnummer, nichts entfernt oder umgedeutet ohne neue Hauptversion. Die Aufgabe nennt jeden geprüften Ordner, listet bei einem Problem alle auf und endet mit einem Fehler, sodass ein CI-Job fehlschlägt. node backend/scripts/module-package.mjs verify <datei>.nxm prüft ein gebautes Paket: Prüfsummen, Dateiliste und die Überschrift im Changelog.

Ohne VS Code: nxm

nxm ist dieselbe Schleife als Kommandozeile, für jeden Editor, für Skripte und für Coding-Agenten wie Claude Code, Codex oder Cursor. Wie die Erweiterung spricht es mit einer Instanz und lässt nichts von nexxus auf Ihrem Rechner laufen; nur Ihre eigenen Dienste laufen lokal, unter Deno.

npm install -g @nexxus-platform/nxm     # Node.js 20.12 oder neuer
nxm init acme.aufgaben                  # ein Paket, das sich so installieren lässt, plus Agenten-Skills
nxm login https://nexxus.example.com    # einmal; fragt nach Ihrem persönlichen API-Token
nxm dev                                 # installiert bei jedem Speichern in den Testmandanten

Das Token liegt im Schlüsselbund Ihres Betriebssystems, wie bei der Erweiterung. Beide nutzen dieselben Testmandanten einer Instanz.

Befehl	Macht
`nxm validate`	Prüft lokal, dann mit den Regeln der Instanz; Probleme erscheinen als `datei:zeile:spalte: meldung`
`nxm dev`	Installiert bei jedem Speichern in den Testmandanten und startet die Dienste unter Deno, mit Inspector auf Port 9229
`nxm apply`	Installiert einmal und endet; `--reset --yes` beginnt neu mit den Beispieldaten
`nxm logs`, `nxm logs -f`	Das Protokoll der Installation, wie im Panel
`nxm replay <id>`	Schickt einen aufgezeichneten Dienstaufruf erneut
`nxm trace <aktion> --record <id>`	Was eine Aktion für einen Datensatz prüfen und tun würde, ohne es zu tun
`nxm open`	Öffnet den Testmandanten, angemeldet als dessen Administrator
`nxm build`, `nxm verify`	Baut die `.nxm` (signiert mit `--key`) und prüft eine
`nxm upload`	Lädt die Version in den verbundenen Mandanten; ein Administrator installiert sie dort

nxm help <befehl> zeigt die Optionen. Mit --json gibt jeder Befehl eine JSON-Zeile aus (nxm logs eine je Eintrag, nxm dev eine je Ereignis), und der Exit-Code ist 0 bei Erfolg, 1 bei einem Fehler, 2 bei einem falschen Aufruf. In CI setzen Sie NXM_URL und NXM_TOKEN, statt sich anzumelden.

Coding-Agenten. nxm init und nxm skills schreiben Skills nach .claude/skills/ und eine AGENTS.md, die auf sie verweist. Sie bringen einem Agenten das Paketformat bei, die Regeln, die nexxus durchsetzt, und die Schleife mit nxm, und sie enthalten diese Dokumentation und das JSON-Schema des Manifests als Referenz, in der Fassung, die zum installierten nxm passt. Ein Agent prüft und installiert seine Änderungen dann selbst mit nxm validate und nxm apply und liest das Ergebnis in nxm logs. Das Token braucht er nie: die Person meldet sich einmal mit nxm login an.

Wie es weitergeht

Ihr erstes ModulEine Liste, ein Dialog und eine Seite, vom Manifest bis zum installierten Paket.

Ansichten und das View-SDKAlle Funktionen des SDK, Gestaltung und die Regeln der Abschottung.

ModuldiensteTokens, Ereignisse, das Service-Kit und das Anbinden eines Dienstes.