Veröffentlichen

Apps befinden sich derzeit in der Alpha-Phase. Die Funktion ist funktionsfähig, entwickelt sich jedoch noch weiter.

Übersicht

Sobald Ihre App lokal gebaut und getestet wurde, haben Sie zwei Möglichkeiten, sie zu verteilen:

Einen Tarball bereitstellen — Laden Sie Ihre App direkt auf einen bestimmten Twenty-Server für die interne oder private Nutzung hoch.
Auf npm veröffentlichen — führen Sie Ihre App im Twenty-Marktplatz auf, damit jeder Arbeitsbereich sie entdecken und installieren kann.

Beide Pfade beginnen mit demselben Build-Schritt.

Erstellen Ihrer App

Führen Sie den Build-Befehl aus, um Ihre App zu kompilieren und eine distributionsfertige manifest.json zu erzeugen:

yarn twenty build

Dabei werden TypeScript-Quelltexte kompiliert, Logikfunktionen und Frontend-Komponenten transpiliert und alles in .twenty/output/ geschrieben. Fügen Sie --tarball hinzu, um zusätzlich ein .tgz-Paket für die manuelle Verteilung oder den Deploy-Befehl zu erzeugen.

Bereitstellung auf einem Server (Tarball)

Für Apps, die Sie nicht öffentlich verfügbar machen möchten — proprietäre Tools, ausschließlich für Unternehmen bestimmte Integrationen oder experimentelle Builds — können Sie einen Tarball direkt auf einem Twenty-Server bereitstellen.

Voraussetzungen

Bevor Sie bereitstellen, benötigen Sie ein konfiguriertes Remote, das auf den Zielserver zeigt. Remotes speichern die Server-URL und Anmeldeinformationen lokal in ~/.twenty/config.json. Ein Remote hinzufügen:

yarn twenty remote add --api-url https://your-twenty-server.com --as production

Bereitstellen

Bauen und laden Sie Ihre App in einem Schritt auf den Server hoch:

yarn twenty deploy
# To deploy to a specific remote:
# yarn twenty deploy --remote production

Eine bereitgestellte App freigeben

Das Teilen privater (Tarball-)Apps über Arbeitsbereiche hinweg ist eine Enterprise-Funktion. Die Registerkarte Distribution zeigt anstelle der Freigabeoptionen eine Aufforderung zum Upgrade an, bis Ihr Arbeitsbereich über einen gültigen Enterprise-Schlüssel verfügt. Gehen Sie zu Einstellungen > Admin-Panel > Enterprise, um es zu aktivieren.

Tarball-Apps werden nicht im öffentlichen Marktplatz gelistet, daher entdecken andere Arbeitsbereiche auf demselben Server sie nicht durch Stöbern. Sobald sich Ihr Arbeitsbereich im Enterprise-Plan befindet, können Sie eine bereitgestellte App wie folgt freigeben:

Gehen Sie zu Einstellungen > Anwendungen > Registrierungen und öffnen Sie Ihre App
Klicken Sie im Tab Distribution auf Freigabelink kopieren
Teilen Sie diesen Link mit Nutzern in anderen Arbeitsbereichen — er führt sie direkt zur Installationsseite der App

Der Freigabelink verwendet die Basis-URL des Servers (ohne Workspace-Subdomain), sodass er für jeden Arbeitsbereich auf dem Server funktioniert.

Versionsverwaltung

Beim Aktualisieren einer bereits bereitgestellten Tarball-App verlangt der Server, dass die version in package.json strikt höher (gemäß der semver-Reihenfolge) ist als die derzeit bereitgestellte Version. Das erneute Bereitstellen derselben Version oder das Pushen einer niedrigeren Version wird abgelehnt, bevor das Tarball gespeichert wird — in der CLI wird ein VERSION_ALREADY_EXISTS-Fehler angezeigt. So veröffentlichen Sie ein Update:

Erhöhen Sie das Feld version in Ihrer package.json (z. B. 1.2.3 → 1.2.4, 1.3.0 oder 2.0.0).
Führen Sie yarn twenty deploy aus (oder yarn twenty deploy --remote production)
Arbeitsbereiche, die die App installiert haben, sehen in ihren Einstellungen, dass ein Upgrade verfügbar ist.

Pre-Release-Tags funktionieren wie erwartet: Das Erhöhen von 1.0.0-rc.1 → 1.0.0-rc.2 ist zulässig, und eine finale Version wie 1.0.0 wird korrekt als höher als 1.0.0-rc.5 erkannt. Die Version in package.json muss selbst eine gültige semver-Zeichenfolge sein.

Auf npm veröffentlichen

Die Veröffentlichung auf npm macht Ihre App im Twenty-Marktplatz auffindbar. Jeder Twenty-Arbeitsbereich kann Marktplatz-Apps direkt über die Benutzeroberfläche durchsuchen, installieren und aktualisieren.

Anforderungen

Ein npm-Konto
Das Schlüsselwort twenty-app in Ihrem package.json-Array keywords (manuell hinzufügen — es ist in der create-twenty-app-Vorlage standardmäßig nicht enthalten)

{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"]
}

Marktplatz-Metadaten

Die defineApplication()-Konfiguration unterstützt optionale Felder, die steuern, wie Ihre App im Marktplatz erscheint. Verwenden Sie logoUrl und screenshots, um Bilder aus dem Ordner public/ zu referenzieren:

src/application-config.ts

export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});

Siehe das defineApplication-Akkordeon auf der Seite Building Apps für die vollständige Liste der Marktplatzfelder (author, category, aboutDescription, websiteUrl, termsUrl usw.).

yarn twenty publish

Um unter einem bestimmten dist-tag zu veröffentlichen (z. B. beta oder next):

yarn twenty publish --tag beta

So funktioniert die Marktplatz-Erkennung

Der Twenty-Server synchronisiert seinen Marktplatzkatalog stündlich aus der npm-Registry. Sie können die Synchronisierung sofort auslösen, anstatt zu warten:

yarn twenty catalog-sync
# To target a specific remote:
# yarn twenty catalog-sync --remote production

Die im Marktplatz angezeigten Metadaten stammen aus Ihrer defineApplication()-Konfiguration — Felder wie displayName, description, author, category, logoUrl, screenshots, aboutDescription, websiteUrl und termsUrl.

Wenn deine App keine aboutDescription in defineApplication() definiert, verwendet der Marktplatz automatisch die README.md deines Pakets von npm als Inhalt der Über-uns-Seite. Das bedeutet, dass du eine einzige README sowohl für npm als auch für den Twenty-Marktplatz pflegen kannst. Wenn du im Marktplatz eine andere Beschreibung möchtest, setze aboutDescription explizit.

CI-Veröffentlichung

Verwenden Sie diesen GitHub-Actions-Workflow, um bei jedem Release automatisch zu veröffentlichen (verwendet OIDC):

name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx twenty build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output

Für andere CI-Systeme (GitLab CI, CircleCI usw.) gelten die gleichen drei Befehle: yarn install, yarn twenty build und anschließend npm publish aus .twenty/output.

npm-Provenance ist optional, wird jedoch empfohlen. Das Veröffentlichen mit --provenance fügt Ihrem npm-Eintrag ein Vertrauensabzeichen hinzu, sodass Nutzer überprüfen können, dass das Paket aus einem bestimmten Commit in einer öffentlichen CI-Pipeline gebaut wurde. Siehe die npm-Provenance-Dokumentation für Einrichtungshinweise.

Apps installieren

Sobald eine App veröffentlicht (npm) oder bereitgestellt (Tarball) wurde, können Arbeitsbereiche sie über die Benutzeroberfläche installieren. Gehen Sie zur Seite Einstellungen > Anwendungen in Twenty, auf der sowohl Marktplatz- als auch per Tarball bereitgestellte Apps durchsucht und installiert werden können. Sie können Apps auch über die Befehlszeile installieren:

yarn twenty install

Der Server erzwingt bei der Installation semver-Versionierung und spiegelt damit die Regeln beim Bereitstellen wider:

Die Installation derselben Version, die in Ihrem Arbeitsbereich bereits installiert ist, wird mit einem APP_ALREADY_INSTALLED-Fehler abgelehnt.
Die Installation einer niedrigeren Version als die aktuell installierte wird mit einem CANNOT_DOWNGRADE_APPLICATION-Fehler abgelehnt.

Um eine neuere Version zu installieren, stellen Sie sie zuerst bereit oder veröffentlichen Sie sie und führen Sie dann yarn twenty install erneut aus.

Entwickler

Erweitern

Selbsthosting

Mitwirken