# Apps programmieren
> Die Referenz für Entwickler, die eine App selbst schreiben: das .nxa-Paket und sein Manifest, das .nxd-Dokumentformat, was eine App in der Sandbox darf, das Nachrichtenprotokoll zwischen App und nexxus, wie der KI-Assistent und Mitbearbeitende Ihre Dokumente ändern, und wie Sie testen und veröffentlichen.
:::note[Ohne Code?]
Um Dokumente anzulegen, eine .nxa-Datei zu installieren oder den KI-Assistenten eine App erstellen zu lassen, lesen Sie [Apps ohne Code erstellen](/de/apps/create/). Diese Seite ist für Entwickler, die das HTML einer App selbst schreiben.
:::
Eine App besteht aus einer HTML-Datei und einer Beschreibungsdatei. Das HTML zeichnet ein Dokument und meldet, was die Person darin ändert. Alles andere erledigt nexxus: Dokument laden und speichern, Versionen, Freigaben, gemeinsames Bearbeiten in Echtzeit, der KI-Assistent, die Rechte. Ihre App berührt nie einen Speicher und sieht nie das Netz. Das hält Apps klein, und deshalb lässt nexxus jeden Apps installieren.
Diese Seite ist der Vertrag. Sie beschreibt, was heute in nexxus ausgeliefert wird.
## Das Paket (.nxa)
Eine App wird als ZIP-Datei mit der Endung `.nxa` ausgeliefert. nexxus liest daraus zwei Einträge, gefunden über ihren Dateinamen, egal wo im Archiv:
- hello.nxa ein ZIP-Archiv
- manifest.json ID, Version, Name, Symbol, Inhaltstyp, Datenschema
- app.html die Oberfläche, alles eingebettet
Andere Einträge ignoriert nexxus. Bauen Sie das Paket mit einem beliebigen ZIP-Werkzeug, zum Beispiel:
```bash
zip -j hello.nxa manifest.json app.html
```
Die Hilfe in der App enthält ein funktionierendes Beispiel: Unter öffnet Hilfe eine Erklärung, und Beispiel-App herunterladen speichert die Datei `hello.nxa`. Jeder Download trägt eine frische ID wie `hello-ab12c`, so lässt sich das Beispiel mehrmals in einem Mandanten installieren.
## Das Manifest
`manifest.json` beschreibt die App. nexxus prüft es vollständig, bevor etwas gespeichert wird: beim Hochladen, bei einer neuen Version und wenn der KI-Assistent eine App registriert.
So sieht das Manifest der Beispiel-App aus, wie nexxus es erzeugt:
```json
{
"id": "hello-ab12c",
"version": 1,
"label": "Hallo-App",
"icon": "waving_hand",
"contentType": "application/json",
"dataKind": "json",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": { "type": "string", "description": "Der angezeigte Text." }
},
"required": ["text"]
}
}
```
### Felder
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `id` | String | ja | Die ID der App und der Wert `$app` ihrer Dokumente. 2 bis 40 Zeichen, Kleinbuchstaben, Ziffern und Bindestriche, am Anfang ein Buchstabe (`[a-z][a-z0-9-]{1,39}`). Eindeutig je Mandant. `board` und `markdown` sind für die eingebauten Apps reserviert. |
| `label` | String | ja | Der Name auf der Karte, im Menü Neu der Dateien und auf der Dokumentseite. |
| `contentType` | String | ja | Wie die Daten beschrieben sind, etwa `application/json`, `text/markdown`, `text/plain` oder `application/xml`. |
| `dataKind` | `"json"` oder `"text"` | ja | `json`: `data` ist ein JSON-Wert, geprüft gegen `schema`. `text`: `data` ist ein String. |
| `schema` | Objekt | bei `json`-Apps | Ein JSON Schema (Draft 2020-12) für `data`. nexxus kompiliert es beim Hochladen und prüft jedes Dokument dagegen, das der KI-Assistent anlegt oder ändert. Text-Apps bekommen `{"type": "string"}`. |
| `description` | String | nein | Steht auf der Karte der App und geht an den KI-Assistenten. |
| `icon` | String | nein | Ein Material-Icon-Name für die Karte. Standard `apps`. |
| `color` | String | nein | Die Farbe der Karte als Hex-Wert. Standard `#1565C0`. |
| `version` | Ganzzahl | nein | Die Version der App, Standard `1`. Jeder neue Upload muss eine höhere Zahl tragen. |
| `defaultData` | beliebig | nein | Der Inhalt eines neuen Dokuments. Ohne das Feld beginnt ein neues Dokument mit `{}` (json) oder einem leeren String (text), und Ihre App muss das darstellen. |
| `aiInstructions` | String | nein | Hinweise für den KI-Assistenten, wie ein gutes Dokument aussieht, höchstens 8000 Zeichen. |
| `changelog` | Array | nein | Was jede Version geändert hat, zu sehen vor einer Veröffentlichung und in der Versionshistorie. |
| `capabilities` | Objekt | nein | Wünsche an den Rahmen um die App: `tabs` und `assistant`. |
| `contributes` | Objekt | nein | Menüeinträge, die die App in die Leiste über sich legt. Höchstens 256.000 Bytes. |
`app.html` darf nicht leer sein und höchstens 2.000.000 Bytes (UTF-8) groß.
### Das Datenschema
Das Schema ist der Vertrag zwischen Ihrer App, nexxus und dem KI-Assistenten. Daraus folgt dreierlei:
- nexxus lehnt jedes Dokument vom KI-Assistenten ab, das nicht passt. Der KI-Assistent bekommt die Fehlermeldung und kann seine Änderung korrigieren.
- Der KI-Assistent lernt Ihr Datenmodell aus dem Schema. Geben Sie jeder Eigenschaft eine `description`. Dort liest der KI-Assistent, was ein Feld bedeutet, welche Einheit es hat und welche Werte sinnvoll sind.
- Dokumente überleben App-Versionen. Fügen Sie neue Eigenschaften als optional hinzu, damit Dokumente aus einer älteren Version gültig bleiben.
Halten Sie `defaultData` leer oder knapp. Soll der KI-Assistent in einem neuen Dokument etwas bauen, wird ihm gesagt, unveränderte Startinhalte zu ersetzen. Ein Demo-Board, das nie verschwindet, ist trotzdem die häufigste Klage über Startinhalte. Gehört eine Einführung dazu, zeigen Sie sie im leeren Zustand Ihrer App. Beim Hochladen prüft nexxus `defaultData` nicht gegen das Schema, das Werkzeug des KI-Assistenten zum Anlegen aber schon: Passt `defaultData` nicht zum Schema, scheitert er an neuen Dokumenten.
### aiInstructions
Das Schema sagt, was gültig ist. `aiInstructions` sagt, was gut ist: Layoutregeln, Größen, Konventionen, die Fehler, die Modelle mit Ihren Daten gern machen. nexxus gibt den Text zusammen mit dem Schema an den KI-Assistenten, sobald jemand an einem Ihrer Dokumente arbeitet, und liefert ihn mit dem Werkzeug, das die Apps auflistet. Auf der Seite der App kann der Besitzer für seinen Mandanten eine Ergänzung hinzufügen; der KI-Assistent bekommt zuerst Ihren Text, dann die Ergänzung.
### changelog
Ein Eintrag je Version, der neueste zuerst. `version` ist eine Ganzzahl ab 1, `changes` eine nicht leere Liste nicht leerer Strings, `date` optional im Format `JJJJ-MM-TT`. Weitere Schlüssel ignoriert nexxus. Das sind die beiden neuesten Einträge der Whiteboard-App:
```json
"changelog": [
{
"version": 7,
"date": "2026-10-04",
"changes": [
"Die App bringt einen Changelog mit. Er erscheint beim Hochladen einer neuen Version und in der Versionshistorie.",
"Die Hinweise für den KI-Assistenten erklären jetzt auch Standardgrößen, wie das Board überlappende Elemente nachbessert, Frames als Spalten und typische Fehler wie doppelte ids."
]
},
{
"version": 6,
"date": "2026-10-03",
"changes": [
"Hell und Dunkel folgen dem Modus der Anwendung, in der das Board läuft.",
"Wer in der App selbst umschaltet, behält diese Wahl für das Whiteboard."
]
}
]
```
Lädt jemand eine neue Version hoch, zeigt der Dialog jeden Eintrag, der neuer ist als die installierte Version, bis zur Version des Pakets. Die Versionshistorie auf der Seite der App nimmt den Eintrag jeder Version aus dem neuesten hochgeladenen Manifest, das einen hat. Ein vollständiger Changelog in einer neuen Version füllt also auch ältere Versionen auf. Schreiben Sie die Punkte für die Menschen, die die App benutzen: eine konkrete Änderung je Punkt.
### capabilities
| Schlüssel | Typ | Standard | Wirkung |
|---|---|---|---|
| `tabs` | Boolean | `false` | nexxus zeigt über der App eine Reihe von Tabs. Das geöffnete Dokument ist der erste Tab, + öffnet eine Auswahl mit den übrigen Dokumenten derselben App und Leeres Dokument. Ein Tabwechsel lädt die App mit dem anderen Dokument neu. |
| `assistant` | Boolean | `true` | `false` erklärt, dass die Dokumente der App nicht für den KI-Assistenten gedacht sind. Der Schalter Assistent für diese App auf der Seite der App bleibt dann aus und lässt sich erst mit einer Version einschalten, die es erlaubt. |
Unbekannte Schlüssel ignoriert nexxus. Was fehlt, ist aus, außer bei `assistant`.
### contributes
Eine App kann Befehle in die Leiste über sich legen, entweder in das stehende Menü Datei oder in eigene Menüs. Ein Klick geht als `nxd:command` mit der ID des Befehls an die App. Das ist der Block des BPMN-Prozess-Editors:
```json
"contributes": {
"commands": [
{ "id": "process.validate", "title": "BPMN prüfen", "category": "Prozess" },
{ "id": "process.export.svg", "title": "Als SVG exportieren", "category": "Datei" }
],
"menus": {
"datei": [ { "command": "process.export.svg", "group": "export" } ],
"menubar": [
{ "id": "prozess", "title": "Prozess", "items": [ { "command": "process.validate" } ] }
]
}
}
```
- `commands` legt Befehle mit `id` und `title` fest. Die erste Angabe einer ID gilt. Die IDs `__proto__`, `constructor` und `prototype` lehnt nexxus ab.
- `menus.datei` hängt Einträge an das Menü Datei an, gruppiert nach `group` und sortiert nach `order`. `datei` ist das einzige stehende Menü, das eine App erweitern kann.
- `menus.menubar` fügt eigene Menüs hinzu, jedes mit `id`, `title`, `items` und optional `order`. Angezeigt werden höchstens 8 Menüs mit je 24 Einträgen.
- An einem fehlerhaften Menüeintrag scheitert kein Manifest. nexxus lässt weg, was es nicht auflösen kann (einen unbekannten Befehl, ein nicht erlaubtes Menü), und warnt in der Browser-Konsole. Weitergereicht werden nur Befehls-IDs, die diese Prüfung bestanden haben.
## Das Dokument (.nxd)
Ein Dokument ist eine JSON-Datei in den Dateien, verpackt in einen kleinen Umschlag:
```json
{
"$app": "board",
"$v": 1,
"contentType": "application/json",
"meta": { "title": "Messe 2026" },
"data": {
"columns": [ { "id": "todo", "title": "To-do" } ],
"cards": []
}
}
```
| Feld | Typ | Bedeutung |
|---|---|---|
| `$app` | String | Die ID der App, die das Dokument öffnet. Pflicht: Ohne das Feld zeigt nexxus Ungültige .nxd-Datei: Feld "$app" fehlt. |
| `$v` | Zahl | Version des Umschlagformats, derzeit `1`. |
| `contentType` | String | Aus dem Manifest übernommen. |
| `meta.title` | String | Der Titel des Dokuments. Er ist auch Teil des Dateinamens. |
| `data` | Objekt oder String | Der Inhalt Ihrer App: was `schema` bei json-Apps beschreibt, ein String bei Text-Apps. |
Der Dateiname lautet `..nxd`, zum Beispiel `Messe 2026.board.nxd`. Beim Anlegen liest nexxus die App-ID aus dem Dateinamen und findet darüber die Dokumente einer App. Welche App ein Dokument öffnet, entscheidet `$app`, nicht der Name. Eine Datei, die kein gültiges JSON ist, zeigt Ungültige .nxd-Datei: kein gültiges JSON.
Ihre App sieht immer nur `data` (und den Titel in `meta`). Der Umschlag ist Sache von nexxus.
## In der Sandbox
nexxus lädt `app.html` in einen iframe mit `sandbox="allow-scripts"`: Ihr Code läuft, aber ohne die Origin von nexxus, also ohne Cookies, ohne Sitzung und ohne Zugriff auf die Seite drumherum. Vor Ihr HTML setzt nexxus diese Content-Security-Policy:
```text
default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:;
font-src data:; media-src data: blob:; form-action 'none'; base-uri 'none'
```
Was das für Ihren Code bedeutet:
| Geht | Geht nicht |
|---|---|
| Eingebettetes `