# 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. 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](#ohne-vs-code-nxm) dasselbe. ## 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](https://git.systaro.de/systaro/nexxus/nexxus/-/jobs/artifacts/main/raw/tools/vscode-nexxus/nexxus-modules.vsix?job=vscode-extension). 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](/de/setup/security/#persönliche-api-tokens). - **Deno 2**, nur wenn Ihr Paket eigene Dienste hat ([Installation](https://docs.deno.com/runtime/getting_started/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: - acme.aufgaben/ - 1.0.0/ - module.json ein Fachobjekt mit Liste und Datensatzansicht, eine eigene Seite, eine Aktion - CHANGELOG.md - ui/ - offen.html - demo/ 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](/de/modules/first-module/). ## Mit einer Instanz verbinden 1. Legen Sie in der App ein API-Token an, wie in [Persönliche API-Tokens](/de/setup/security/#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. 2. 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. :::note[Eine lokale Instanz] Lokal antwortet die API auf `http://localhost:7040` und die App auf `http://localhost:7041`. Verbinden Sie sich mit 7040 und setzen Sie die Einstellung `nexxus.appUrl` auf `http://localhost:7041`, damit die Erweiterung die richtigen Seiten öffnet. Auf einer Instanz im Netz teilen sich App und API eine Adresse; lassen Sie die Einstellung dann leer. ::: ## Probleme beim Speichern 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. :::note[Ohne die Erweiterung] 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 { "json.schemas": [ { "fileMatch": ["**/module.json"], "url": "./module-package.schema.json" } ] } ``` ::: ## Der Dev-Modus: Änderungen beim Speichern sichtbar ### 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: 1. 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`. 2. Beim ersten Mal installiert die Instanz das Paket mit seinen Beispieldaten und gibt Ihnen jede Rolle des Pakets, ohne Dialog. 3. 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. 4. 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 Bringt Ihr Paket eigene [Dienste](/de/modules/services/) mit (`services` in `module.json`), liegt ihr Code im Versionsordner unter `services//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 `//events` und `//actions/`, 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. :::note[Ohne die Erweiterung] Ein Dienst läuft außerhalb von nexxus, also auch auf Ihrem Rechner. Starten Sie ihn selbst und richten Sie die Installation mit der Installationseinstellung `serviceUrls.` auf ihn aus, wie in [Einen Dienst auf einer Instanz anbinden](/de/modules/services/#einen-dienst-auf-einer-instanz-anbinden) beschrieben. Die Instanz muss Ihren Rechner dann erreichen können; eine lokale kann das. ::: ## Debuggen 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//`. 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: ```json { "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](/de/modules/views/#das-protokoll-zur-fehlersuche). ## Sehen, was passiert ist: das Protokoll Jede Installation hat ein Protokoll. Sie finden es auf ihrer Paketseite unter , 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 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** . 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** . 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/-.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](/de/modules/publish/#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: ```bash ./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 `/` 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 .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. ```bash 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 ` | Schickt einen aufgezeichneten Dienstaufruf erneut | | `nxm trace --record ` | 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 ` 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