Skip to content

Getting Started Guide for extension development #896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
freisenhauer wants to merge 12 commits into
base: master
Choose a base branch
from
Draft

Getting Started Guide for extension development #896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
495a62d
check in first parts of getting started guide for extension development
freisenhauer-mittwald Jan 15, 2026
3e14ec7
add expose extension chapter to getting started guide
freisenhauer-mittwald Jan 16, 2026
bcb803f
add step of configuring scopes to getting started guide
freisenhauer-mittwald Jan 21, 2026
21ca4ec
edit step of starting the reference extension locally to use docker
freisenhauer-mittwald Jan 21, 2026
52eed70
fix typo
freisenhauer-mittwald Jan 21, 2026
18d8fb1
add step of testing inside mStudio to getting started guide
freisenhauer-mittwald Jan 21, 2026
8842f35
add deployment step to getting started guide
freisenhauer-mittwald Jan 21, 2026
9b87800
add note that propably a server is needed for extension development t…
freisenhauer-mittwald Jan 21, 2026
8dfe967
start to write next steps for getting started
freisenhauer-mittwald Jan 24, 2026
2edcb94
add becoming contributor to getting started guide
freisenhauer-mittwald Jan 29, 2026
d9298a9
fix typo
freisenhauer-mittwald Jan 30, 2026
aeb4f61
add guide of how to implement external frontend to getting started guide
freisenhauer-mittwald Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ npm-debug.log*
yarn-debug.log*
yarn-error.log*

/tmp

# Generated by the build process
/sidebar.reference.json

Expand Down
1 change: 1 addition & 0 deletions docs/contribution/20-glossary.mdx → docs/contribution/10-glossary.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: Glossary
sidebar_position: 2
---

## Contributor
Expand Down
36 changes: 36 additions & 0 deletions docs/contribution/20-getting-started/02-become-contributor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
title: Contributor werden
---

Contributor werden ist sehr einfach.
Du brauchst lediglich eine Organisation, die du über das mStudio anlegen kannst.
Organisationen repräsentieren Unternehmungen, über die etwas abgerechnet werden kann.
Bei unseren Hosting-Produkten sind dies bspw. Rechnungen.
Im Falle von Contributoren werden die Gutschriften für die gebuchten Extensions über die Organisation gutgeschrieben.

:::info Separate Organisation
Wenn du bereits konventioneller Kunde bei uns im mStudio bist,
könnte es von Vorteil sein, eine separate Organisation für die Contribution zu erstellen,
um die beiden Geschäftsbereiche zu trennen und Berechtigungen einfacher abzugrenzen.
Dies ist jedoch keine Pflicht.
:::

Um Contributor zu werden, muss in deiner Organisation zunächst ein Vertragspartner hinterlegt werden

![Vertragspartner hinzufügen](/img/contribution/getting-started-guide/add-contract-owner.png)

![Vertragspartner konfigurieren](/img/contribution/getting-started-guide/contract-owner.png)

Nun kann einfach auf den Button **"Contributor werden"** geklickt werden.
Dadurch wird deine Organisation zu einem unverifizierten Contributor.
Falls du deine Extension veröffentlichen willst, folge diesem Guide bis zur [Veröffentlichung der Extension](../publish)

![Contributor werden](/img/contribution/getting-started-guide/become-contributor.png)

:::info
Um Extensions nicht nur für dich, sondern für die Allgemeinheit bereitstellen zu können,
musst du als Contributor verifiziert werden.

Eine genaue Übersicht darüber, welche Informationen für die Verifizierung eines Contributors benötigt werden,
haben wir in unserer [Contributor Übersicht](../../overview/contributor) beschrieben.
:::
90 changes: 90 additions & 0 deletions docs/contribution/20-getting-started/03-configure-extension.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
---
title: Konfiguration der Extension
---

## Extension registrieren

Sobald man Contributor ist, kann eine Extension im mStudio angelegt werden.
Dazu muss innerhalb der Organisation der **"Entwicklung" Tab** aufgerufen werden und über den **"Anlegen" Button** eine neue Extension registriert werden.
Zu diesem Zeitpunkt muss lediglich ein **Name** eingegeben werden, der auch im **Nachhinein noch ändern** kann.

Extension Namen müssen **eindeutig** sein.
Da es sich empfiehlt, für die **Entwicklung vorerst eine eigene** und später für produktive Zwecke eine weitere Extension anzulegen,
ist es sinnvoll, dies im Namen zu vermerken, indem bspw. "(DEV)" an den Namen angehangen wird.

:::info Lebenszyklus von Extensions
Extensions sind erst im Marktplatz **sichtbar**, wenn sie **veröffentlicht** wurden.
Deswegen können problemlos für eigene Entwicklungsprozesse Entwicklungs- bzw. Staging-Extensions angelegt werden.
Weitere Informationen zum Lebenszyklus von Extensions sind im [Extension Konzept](../../overview/extensions#lifecycle-of-an-extension) erklärt.
:::

![Extension registrieren](/img/contribution/getting-started-guide/register-extension.png)

## Setzen des Extension Context

Für jede Extension muss festgelegt werden, in **welchem Kontext** sie **installierbar** sein soll.
Zur Auswahl stehen **Organisation** und **Projekt**.
Die Reference Extension ist als Projekt-Extension gebaut.

Im **Tab "Berechtigungen"** muss also in der Sektion **Extension Context** auf **Bearbeiten** geklickt werden.
Nun wird **Projekt** gewählt und gespeichert.

:::info Wahl des Extension Context
Die Reference Extension ist als Projekt-Extension gebaut.
Es ergibt jedoch nicht für jede Extension-Idee sinn, sie als Projekt-Extension zu implementieren.

Welche Auswirkungen die Wahl hat und welche Faktoren für die Wahl entscheidend sind, haben wir im ["Wie wähle ich den richtigen Extension Context?"-Guide](../../how-to/choose-a-context) beschrieben.
:::

![Extension Context](/img/contribution/getting-started-guide/extension-context.png)

## Berechtigungen konfigurieren

Die Reference Extension ruft Informationen über den User und das Projekt, in dem sie installiert ist, ab.
Außerdem bietet sie die Möglichkeit, den Namen des Projekts anzupassen.
Um dazu in der Lage zu sein, müssen für die Extension Berechtigungen in Form von Scopes konfiguriert werden.
Das muss immer gemacht werden, wenn Extensions auf die mStudio API zugreifen wollen.

Genauso wie der Extension Context werden auch die Berechtigungen im **Tab "Berechtigungen"** konfiguriert.
Dazu muss in der entsprechende Sektion auf "Bearbeiten" geklickt werden.
Wir stellen nun **Projekt lesen** und **schreiben** sowie **Benutzer lesen** ein.

:::info Verfügbare Scopes
Im [Guide zu Scopes](../../overview/concepts/scopes) haben wir ausführlicher beschrieben, welche Scopes verfügbar sind und wie der richtige Scope identifiziert werden kann.
Wenn du Schwierigkeiten damit hast, den richtigen Scope zu finden oder dein Scope fehlt, komm gerne auf uns zu.
Wir unterstützen dich gerne dabei.
:::

![Berechtigungen einstellen](/img/contribution/getting-started-guide/scopes.png)

## Konfigurieren der Frontend-URL

Die Reference Extension verwendet ein **Frontend Fragment**.
Das bedeutet, sie implementiert ein Frontend, dass nahtlos in das mStudio integriert werden soll.

:::info Frontend Fragment vs. External Frontend
Frontend Fragmente sind nicht die einzige Möglichkeit, ein Frontend für eine Extension anzubieten.
Wenn die Anforderungen an Frontend Fragmenten für dich zu restriktiv sind oder nicht zu deinem Anwendungsfall geeignet sind,
gibt es auch die Möglichkeit, ein externes Frontend zu implementieren.

Die Eigenschaften und Unterschiede zwischen Frontend Fragmenten und externen Frontends sind im [Konzept zur Frontend Entwicklung](../../overview/concepts/frontend-development) erklärt
:::

Um die URL für das Frontend Fragment der Reference Extension einzustellen, muss im **Tab "Frontend"** der Extension in der Sektion zu **Frontend Fragments** auf **Hinzufügen** geclickt werden.

![Frontend Fragment hinzufügen](/img/contribution/getting-started-guide/frontend-fragments.png)

Für ein Frontend Fragment muss ein **Ankerpunkt** gewählt werden.
Dieser bestimmt, an welcher Stelle das Frontend deiner Extension eingebunden werden soll.
Die Reference Extension ist gebaut, um an dem Ankerpunkt `/projects/project/menu/section/extensions/item` eingehangen zu werden,
also als Menüpunkt innerhalb eines Projekts.

Für den Ankerpunkt muss außerdem ein **Anzeigename** definiert werden.
Dieser bestimmt bspw. bei Ankerpunkten, die als Menüpunkte fungieren, wie der Menüpunkt heißt.
Für Sektionen bestimmt der Anzeigename die Überschrift der Sektion.

Schließlich muss eine **URL** angegeben werden.
Für die in Entwicklung befindliche Extension kann hier auch eine auf dem **lokalen Client erreichbare Adresse** eingegeben werden.
Da die Reference Extension Standardmäßig auf Port 3000 läuft, fügen wir hier `http://localhost:3000` ein.

![Konfiguration des Frontend Fragments](/img/contribution/getting-started-guide/frontend-fragment-configuration.png)
198 changes: 198 additions & 0 deletions docs/contribution/20-getting-started/04-reference-extension.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
---
title: Reference Extension
---

## Die Reference Extension

Die [Reference Extension](https://github.com/mittwald/reference-extension) ist eine umfassende Beispiel-Extension,
die alle wichtigen Features für die Entwicklung von Extensions, die sich direkt in das mStudio integrieren, demonstriert.
Sie dient als praktische Vorlage und Lernressource für Entwickler.

### Idee und Motivation

Die Reference Extension wurde entwickelt, um:

- **Best Practices** für Extension-Entwicklung zu zeigen
- Alle wichtigen **Marketplace-Konzepte** praktisch zu demonstrieren
- Die Integration mit der mittwald API und dem mStudio zu illustrieren
- Als **Ausgangspunkt** für eigene Extension-Projekte zu dienen

Die Extension ist vollständig dokumentiert und kann als Template verwendet werden, um eigene Extensions zu entwickeln.
Der Code ist so strukturiert, dass er leicht verstanden, angepasst und erweitert werden kann.

### Technologischer Stack

Die Reference Extension verwendet moderne Web-Technologien, die auch für die Entwicklung eigener Extensions empfohlen werden:

**Frontend:**

- **[React 19](https://react.dev/)** - Für die Entwicklung der Benutzeroberfläche
- **[TanStack Router & Query](https://tanstack.com/)** - Routing und State Management
- **[@mittwald/flow-remote-react-components](https://mittwald.github.io/flow/)** - UI-Framework, das mit Frontend Fragmenten kompatibel ist
- **[React Ghostmaker](https://github.com/mittwald/react-ghostmaker)** - Server Function Abstraktion

**Backend:**

- **[TanStack Start](https://tanstack.com/start/latest)** - Full-stack React Framework
- **[Drizzle ORM](https://orm.drizzle.team/)** - Typsichere Datenbankoperationen mit PostgreSQL
- **[@mittwald/api-client](https://www.npmjs.com/package/@mittwald/api-client)** - Client für die mittwald API
- **[@weissaufschwarz/mitthooks](https://www.npmjs.com/package/@weissaufschwarz/mitthooks)** - Webhook-Verarbeitung

**Development Tools:**

- **[Vite](https://vite.dev/)** - Schnelles Build-Tool
- **[Biome](https://orm.drizzle.team/)** - Linting & Formatting
- **[Vitest](https://vitest.dev/)** - Unit Testing Framework

### Implementierte Konzepte des mStudio Marktplatzes

Die Reference Extension demonstriert alle wichtigen Konzepte, die für die Entwicklung von Extensions, die direkt im mStudio eingebunden werden sollen, relevant sind:

**1. Lifecycle Webhooks**

- Verarbeitung von Lifecycle Events (create, update, remove), um einen State über bestehende Extension Instances aufbauen zu können
- Speicherung der Instance-Daten in eigener Datenbank
- Validierung der Webhook Signatur, um Missbrauch zu verhindern

Weitere Informationen zum Zweck und der Funktionsweise von Lifecycle Webhooks können im [Konzeptdokument zu Lifecycle Webhooks](../../overview/concepts/lifecycle-webhooks) nachgelesen werden.

**2. Frontend Fragments**

- Rendering von UI-Komponenten im mStudio via Remote DOM
- Integration als Menüeintrag im Projekt-Kontext
- Verwendung des Anchor Points: `/projects/project/menu/section/extensions/item`

Im ["Wie man ein Frontend-Fragment entwickelt"](../../how-to/develop-frontend-fragment)-Guide findest du detailiertere Informationen zur Funktionsweise von Frontend Fragmenten und dem Remote-DOM.

:::info Wichtiger Hinweis zu Frontend Fragments
Um Frontend direkt in das mStudio integrieren zu können, muss ein Remote DOM bereit gestellt werden.
Das Bootstrapping der Reference Extension übernimmt das für dich.
Das Remote DOM im mStudio erfordert die Verwendung von **Flow Design System Komponenten**.
Standard HTML-Elemente wie `<div>` oder `<button>` funktionieren **nicht** im Remote DOM.
Verwende stattdessen Flow-Komponenten wie `<Section>`, `<Button>` aus `@mittwald/flow-remote-react-components`.
:::

**3. mStudio API Integration**

- Session Token Handling für sichere Kommunikation
- Verwendung von Access Tokens für API-Authentifizierung
- Abrufen und Modifizieren von Projekt-Daten

Die Reference Extension implementiert für dich eine Middleware,
die dir sowohl ein Access Token als auch einen bereits authentifizierten API-Client für die mStudio API bereitstellt.
Dieser API-Client kann verwendet werden, um Ressourcen aus dem mStudio abzurufen oder zu modifizieren.

Außerdem sind ein paar Server Functions implementiert, die den Einsatz der Middleware sowie die Nutzung des API-Clients demonstrieren.

[//]: # "TODO Referenz auf Session Token authentifizierungskonzept, sobald die Seite überarbeitet wurde"

**4. Custom Data Persistence**

- Eigene PostgreSQL-Datenbank für Extension-spezifische Daten
- Drizzle ORM für typsichere Datenbankoperationen
- Schema-Migrations mit Drizzle Kit

:::info Repository Dokumentation
Für eine detaillierte Übersicht der Repository-Struktur und Architektur-Patterns,
siehe die [umfangreiche Dokumentation im Reference Extension Repository](https://github.com/mittwald/reference-extension).
:::

## Die Reference Extension lokal hochfahren

Um die Reference Extension lokal zu entwickeln und zu testen, müssen zunächst einige Voraussetzungen erfüllt und Schritte durchgeführt werden.

**Voraussetzungen:**

- **Node.js 22** (erforderlich)
- **pnpm 9.14.4+** (Package Manager)
- **Docker & Docker Compose** (für PostgreSQL)

### Clonen der Reference Extension und Installieren der Dependencies

Klone zunächst die Reference Extension und installiere die Dependencies:

```bash
# Repository klonen
git clone https://github.com/mittwald/reference-extension.git
cd reference-extension

# Dependencies installieren
pnpm install
```

### Umgebungsvariablen konfigurieren

Die Reference Extension benötigt verschiedene Umgebungsvariablen für die Konfiguration. Erstelle eine `.env` Datei im Projekt-Root:

```bash
cp .env.example .env
```

Auch wenn noch nicht alle der erforderlichen Umgebungsvariablen gesetzt werden können, können die folgenden bereits gesetzt werden:

```env
EXTENSION_ID=
EXTENSION_SECRET=
ENCRYPTION_MASTER_PASSWORD=
ENCRYPTION_SALT=
```

#### EXTENSION_ID

Die Extension ID ist eine bei der Registrierung der Extension generierte UUID und kann im mStudio im **Tab "Details"** eingesehen werden.

![Extension ID](/img/contribution/getting-started-guide/extension-id.png)

#### EXTENSION_SECRET

[//]: # "TODO Extension Secret über das Frontend"

#### ENCRYPTION_MASTER_PASSWORD und ENCRYPTION_SALT

Die Reference Extension verwendet Lifecycle Webhooks, um in der eigenen Datenbank einen State über die laufenden Extension-Instanzen aufzubauen.
Dabei wird ein Extension Instance Secret ausgetauscht, das verschlüsselt und sicher gespeichert werden muss.
Die Reference Extension übernimmt die eigentliche Verschlüsselung.
Dafür wird ein **Master Password** und ein **Salt** benötigt, aus denen ein symmetrischer Schlüssel abgeleitet wird.

Master Password & Salt gelten **pro Extension** und müssen nicht für jede Extension Instance unterschiedlich sein.
Der **Initialization Vektor** bzw. die Nonce wird automatisch für jede Verschlüsselung neu erzeugt, um gleiche Klartexte sicher zu differenzieren.

Um dieses **Secret-Paar** zu **generieren**, rufe in der Reference Extension folgendes Package Script auf:

```bash
pnpm init:encryption
```

Dabei werden die generierten Secrets in die eben erstellte .env Datei geschrieben.

:::info Verschlüsselung von eigenen schützenswerten Feldern
Die Verschlüsselung der Tabellenspalte ist ausreichend modular gebaut, um sie auch für **eigene schützenswerte Felder** verwenden zu können.
Mehr dazu in

[//]: # "TODO Referenz auf Kapitel, in dem beschrieben wird, wie eigene Felder verschlüsselt werden können"

:::

### Starten der Entwicklungsumgebung

Die Reference Extension ist auf eine Datenbank angewiesen für die Persistierung ihrer Daten.
Sie verwendet dazu **[PostgreSQL](https://www.postgresql.org/)**.

Um das Starten der Extension zu vereinfachen, liefert die Reference Extension eine `docker-compose.yml` sowie eine `docker-compose.dev.yml`.
Beide können dazu werden, die Extension vollständig mit ihren Abhängigkeiten zu starten.
Die `docker-compose.dev.yml` startet die Extension jedoch in einem Development Modus mit Hot Reloading.

Um die Extension zu starten, führe den folgenden Befehl aus:

```bash
pnpm run docker:dev
```

Das **Datenbank Schema** wird durch die Extension automatisch über **Migrations** angewandt.
Die Extension läuft nun auf **Port 3000** und ist unter `http://localhost:3000` erreichbar.

:::warning Public URL erforderlich
Damit die Extension im mStudio funktioniert, muss die lokal laufende Extension eine tatsächliche Extension Instance speichern.
Dafür muss sie über eine **öffentlich erreichbare URL** verfügbar sein.
Im nächsten Schritt erfährst du, wie du mit einem Tunneling-Service wie **zrok** eine öffentliche URL bereitstellst.
:::
Loading
Loading