Publikování

Přehled

Jakmile je vaše aplikace sestavena a otestována lokálně, máte dvě cesty, jak ji distribuovat:

Nasaďte tarball — nahrajte svou aplikaci přímo na konkrétní server Twenty pro interní nebo soukromé použití.
Publish to npm — uveďte svou aplikaci v Marketplace Twenty, aby ji mohl kterýkoli pracovní prostor objevit a nainstalovat.

Obě cesty začínají stejným krokem build.

Sestavení vaší aplikace

Spusťte příkaz build ke zkompilování své aplikace a k vygenerování souboru manifest.json připraveného k distribuci:

yarn twenty dev:build

Tím se zkompilují zdrojové soubory TypeScriptu, transpilují logické funkce a frontendové komponenty a vše se zapíše do .twenty/output/. Přidejte --tarball, abyste také vytvořili balíček .tgz pro ruční distribuci nebo příkaz publish.

Nasazení na server (tarball)

U aplikací, které nechcete zpřístupnit veřejně — proprietární nástroje, integrace pouze pro enterprise nebo experimentální buildy — můžete nasadit tarball přímo na server Twenty.

Předpoklady

Před nasazením potřebujete nakonfigurovaný vzdálený cíl směřující na cílový server. Vzdálené cíle ukládají adresu URL serveru a přihlašovací údaje lokálně v ~/.twenty/config.json. Přidat vzdálený cíl:

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

Nasazení

Sestavte a nahrajte svou aplikaci na server v jednom kroku:

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

Sdílení nasazené aplikace

Aplikace ve formě tarball nejsou uvedeny ve veřejném tržišti, takže je ostatní pracovní prostory na tomtéž serveru procházením neobjeví. Chcete-li sdílet nasazenou aplikaci:

Přejděte do Nastavení > Aplikace > Registrace a otevřete svou aplikaci
Na kartě Distribuce klikněte na Zkopírovat odkaz ke sdílení
Sdílejte tento odkaz s uživateli v jiných pracovních prostorech — zavede je přímo na instalační stránku aplikace

Odkaz ke sdílení používá základní adresu URL serveru (bez jakékoli subdomény pracovního prostoru), takže funguje pro libovolný pracovní prostor na serveru.

Správa verzí

Při aktualizaci již nasazené tarballové aplikace server vyžaduje, aby hodnota version v package.json byla přísně vyšší (podle řazení semver) než aktuálně nasazená verze. Opětovné nasazení stejné verze nebo odeslání nižší verze je odmítnuto ještě před uložením tarballu — v CLI uvidíte chybu VERSION_ALREADY_EXISTS. Chcete-li vydat aktualizaci:

Zvyšte hodnotu pole version v souboru package.json (např. 1.2.3 → 1.2.4, 1.3.0 nebo 2.0.0)
Spusťte yarn twenty app:publish --private (nebo yarn twenty app:publish --private --remote production)
Pracovní prostory, které mají aplikaci nainstalovanou a mají pro ni povolené automatické aktualizace (na kartě Nastavení aplikace), jsou na pozadí aktualizovány automaticky; ostatní uvidí dostupnou aktualizaci ve svém nastavení

Předběžné tagy fungují podle očekávání: zvýšení z 1.0.0-rc.1 → 1.0.0-rc.2 je povoleno a finální vydání jako 1.0.0 je správně rozpoznáno jako vyšší než 1.0.0-rc.5. Verze v package.json musí být platným řetězcem semver.

Kompatibilita verze serveru

Pokud vaše aplikace používá funkci zavedenou v konkrétní verzi serveru Twenty (například poskytovatelé OAuth přidaní ve verzi 2.3.0), měli byste deklarovat minimální verzi serveru, kterou vaše aplikace vyžaduje, pomocí pole engines.twenty v package.json:

{
  "name": "twenty-my-app",
  "version": "1.0.0",
  "engines": {
    "node": "^24.5.0",
    "twenty": ">=2.3.0"
  }
}

Hodnota je standardní rozsah SemVer. Běžné vzory:

Rozsah	Význam
`>=2.3.0`	Jakýkoli server od verze 2.3.0 výše
`>=2.3.0 \<3.0.0`	2.3.0 nebo novější, ale pod další hlavní verzí
`^2.3.0`	Stejné jako `>=2.3.0 \<3.0.0`

Co se děje při nasazení a instalaci:

Pokud je engines.twenty nastaveno a verze cílového serveru nevyhovuje rozsahu, nasazení (nahrání tarballu) nebo instalace je odmítnuto chybou SERVER_VERSION_INCOMPATIBLE a zprávou, která uvádí jak požadovaný rozsah, tak skutečnou verzi serveru.
Pokud engines.twenty není nastaveno, aplikace je přijata na jakékoli verzi serveru (zpětně kompatibilní se stávajícími aplikacemi).
Pokud server nemá nakonfigurované APP_VERSION, kontrola se přeskočí.

Server je rozhodující autoritou — ověřuje engines.twenty jak při nahrání tarballu, tak při instalaci do pracovního prostoru. Pokud nasazujete tarball mimo standardní proces nebo instalujete z marketplace, server přesto vynucuje kompatibilitu.

Automatizované CI/CD (předpřipravené workflowy)

Aplikace vygenerované pomocí create-twenty-app jsou hned připravené se třemi workflowy GitHub Actions ve složce .github/workflows/. CI běží bez jakéhokoli nastavování, CD vyžaduje jediný secret a publikování na npm vyžaduje jednorázové nastavení npm trusted-publisher.

CI — `ci.yml`

Automaticky spouští integrační testy při každém pushi do main a u pull requestů. K čemu slouží:

Provede checkout zdrojového kódu vaší aplikace.
Spustí izolovanou testovací instanci Twenty pomocí složené akce twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main (ekvivalent v CI k yarn twenty docker:start --test).
Povolí Corepack, nastaví Node.js podle vašeho .nvmrc a nainstaluje závislosti pomocí yarn install --immutable.
Spustí yarn test a předá TWENTY_API_URL a TWENTY_API_KEY ze spuštěné instance, aby vaše testy mohly komunikovat se skutečným serverem.

Konfigurační volby:

TWENTY_VERSION (env, výchozí hodnota latest) — uzamkněte v CI používanou verzi serveru Twenty úpravou této hodnoty v ci.yml.
Souběžné běhy jsou seskupeny podle github.ref a při nových pushích ruší právě probíhající běhy.

Nejsou potřeba žádné secrety — testovací instance je efemérní a existuje pouze po dobu běhu úlohy.

CD — `cd.yml`

Nasazuje vaši aplikaci na nakonfigurovaný server Twenty při každém pushi do main a volitelně také z pull requestu, pokud je přidán štítek deploy. K čemu slouží:

Provede checkout headu PR (u označených PR) nebo pushnutého commitu.
Spustí twentyhq/twenty/.github/actions/deploy-twenty-app@main — ekvivalent v CI k yarn twenty app:publish --private.
Spustí twentyhq/twenty/.github/actions/install-twenty-app@main, aby se nově nasazená verze nainstalovala do cílového pracovního prostoru.

Požadovaná konfigurace:

Nastavení	Kde	Účel
`TWENTY_DEPLOY_URL`	`env` v `cd.yml` (výchozí `http://localhost:3000`)	Server Twenty, na který se nasazuje. Před prvním použitím to změňte na skutečnou URL vašeho serveru.
`TWENTY_DEPLOY_API_KEY`	GitHub repozitář Settings → Secrets and variables → Actions	API klíč s oprávněním k nasazení na cílovém serveru.

Výchozí TWENTY_DEPLOY_URL http://localhost:3000 je pouze zástupná hodnota — z runneru hostovaného GitHubem tato adresa nebude dosažitelná. Před povolením CD ji aktualizujte na veřejnou URL vašeho serveru (nebo použijte self-hosted runner s přístupem do sítě).

Spuštění náhledového nasazení z PR: Přidejte k pull requestu štítek deploy. Podmínka if: v cd.yml spustí úlohu pro dané PR s použitím head commitu PR, což vám umožní ověřit změnu na cílovém serveru před sloučením.

Publish — `publish.yml`

Publikuje vaši aplikaci na npm s doloženým původem, když odešlete tag verze (např. v1.0.0), nebo když workflow spustíte ručně na kartě Actions. K čemu slouží:

Načte repozitář vaší aplikace, nastaví Node.js a aktualizuje npm (důvěryhodné publikování vyžaduje npm 11.5.1 nebo novější).
Spustí yarn twenty app:publish, který sestaví aplikaci a publikuje .twenty/output na npm. V CI automaticky přidá --provenance a --access public, takže ve workflowu nejsou potřeba žádné přepínače.

Jednorázové nastavení: Na npmjs.com otevřete svůj balíček > Settings → Trusted Publisher a zaregistrujte tento repozitář s workflowem publish.yml (viz dokumentaci k důvěryhodnému publikování na npm). Publikování s provenance potvrzuje, který repozitář na GitHubu balíček sestavil, a zároveň tak uplatňujete vlastnictví své aplikace na tržišti Twenty.

npm přijímá údaje o původu pouze z veřejných zdrojových repozitářů. Pokud publikujete ze soukromého repozitáře, npm odmítne balíček údajů o původu OIDC s chybou E422 ... Unsupported GitHub Actions source repository visibility: "private" error. Chcete-li publikovat ze soukromého repozitáře, vypněte prokazování původu nastavením TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' v env publikačního kroku (ve vygenerovaném publish.yml je uveden zakomentovaný tip):

      - name: Publish to npm
        env:
          TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
        run: yarn twenty app:publish

Připnutí verzí znovupoužitelných akcí

Workflowy ci.yml a cd.yml odkazují na znovupoužitelné akce na @main, takže aktualizace akcí v repozitáři twentyhq/twenty se přeberou automaticky. Pokud chcete deterministická sestavení, nahraďte @main v každém řádku uses: za commit SHA nebo tag vydání.

Publikování na npm

Publikování na npm zajistí, že bude vaše aplikace dohledatelná v Marketplace Twenty. Jakýkoli pracovní prostor Twenty může procházet, instalovat a aktualizovat aplikace z Marketplace přímo z UI.

Požadavky

Účet na npm
Klíčové slovo twenty-app ve vašem poli keywords v souboru package.json (přidejte ho ručně — ve výchozím nastavení není zahrnuto v šabloně create-twenty-app)

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

Metadata tržiště

Konfigurace defineApplication() podporuje volitelná pole, která určují, jak se vaše aplikace zobrazuje v tržišti. Použijte logo a galleryImages k odkazování na obrázky ze složky public/:

src/application-config.ts

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

Podívejte se na sekci defineApplication na stránce Building Apps pro úplný seznam polí tržiště (author, category, aboutDescription, websiteUrl, termsUrl atd.).

Doporučené rozměry obrázků v galerii

Tržiště zobrazuje galleryImages v pevném kontejneru s poměrem stran 8:5 (například 1600×1000 px).

Obrázky v galerii libovolného poměru stran se zobrazují celé a nikdy se neořezávají, ale cokoli výrazně vyššího nebo užšího než 8:5 bude mít po stranách prázdné pruhy.

Limit velikosti obrázku

Soubor logo a každý soubor v galleryImages nesmí překročit 10 MB. Větší soubory jsou při přesunu vašich publikovaných souborů na servery marketplace vynechány, takže se nezobrazí.

yarn twenty app:publish

Chcete-li publikovat pod konkrétním dist-tagem (např. beta nebo next):

yarn twenty app:publish --tag beta

Jak funguje objevování v tržišti

Server Twenty synchronizuje svůj katalog tržiště z registru npm každou hodinu. Synchronizaci můžete spustit okamžitě místo čekání:

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

Metadata zobrazená na tržišti pocházejí z vaší konfigurace defineApplication() — viz výše Metadata tržiště.

Pokud vaše aplikace nedefinuje aboutDescription v defineApplication(), tržiště automaticky použije soubor README.md vašeho balíčku z npm jako obsah stránky O aplikaci. To znamená, že můžete spravovat jediný soubor README jak pro npm, tak pro tržiště Twenty. Pokud chcete v tržišti jiný popis, explicitně nastavte aboutDescription.

Publikování pomocí CI

Vygenerované workflow publish.yml popsané výše publikuje na npm automaticky při verzovacích tagách, s provenance. Protože yarn twenty app:publish při běhu v CI přidá --provenance a --access public za vás, workflow nepotřebuje žádné přepínače npm — pouze jednorázové nastavení důvěryhodného vydavatele. Pro jiné CI systémy (GitLab CI, CircleCI atd.) spusťte yarn install a poté yarn twenty app:publish. Provenance se vydává, pokud prostředí umí vytvořit token OIDC, a v opačném případě se automaticky vynechá.

npm provenance přidává k vašemu záznamu na npm odznak důvěryhodnosti a umožňuje uživatelům ověřit, že balíček byl sestaven z konkrétního commitu ve veřejné CI pipeline. Také vám umožňuje uplatnit vlastnictví vaší aplikace na tržišti Twenty. Podrobnosti najdete v dokumentaci k npm provenance.

Instalace aplikací

Jakmile je aplikace publikována (npm) nebo nasazena (tarball), mohou ji pracovní prostory nainstalovat prostřednictvím uživatelského rozhraní. Přejděte na stránku Nastavení > Aplikace v Twenty, kde lze procházet a instalovat jak aplikace z tržiště, tak aplikace nasazené jako tarball. Aplikace můžete nainstalovat také z příkazového řádku:

yarn twenty app:install

Server při instalaci vynucuje verzování semver a zrcadlí pravidla pro nasazení:

Instalace stejné verze, která je již nainstalována ve vašem pracovním prostoru, je odmítnuta s chybou APP_ALREADY_INSTALLED.
Instalace nižší verze, než je aktuálně nainstalovaná, je odmítnuta s chybou CANNOT_DOWNGRADE_APPLICATION.

K instalaci novější verze ji nejprve nasaďte nebo publikujte, poté znovu spusťte yarn twenty app:install.

Přehled

Aplikace

API

Vlastní hosting

Přispět

Publikování

Přehled

Sestavení vaší aplikace

Nasazení na server (tarball)

Předpoklady

Nasazení

Sdílení nasazené aplikace

Správa verzí

Kompatibilita verze serveru

Automatizované CI/CD (předpřipravené workflowy)

CI — `ci.yml`

CD — `cd.yml`

Publish — `publish.yml`

Připnutí verzí znovupoužitelných akcí

Publikování na npm

Požadavky

Metadata tržiště

Doporučené rozměry obrázků v galerii

Limit velikosti obrázku

Publikování

Jak funguje objevování v tržišti

Publikování pomocí CI

Instalace aplikací

​Přehled

​Sestavení vaší aplikace

​Nasazení na server (tarball)

​Předpoklady

​Nasazení

​Sdílení nasazené aplikace

​Správa verzí

​Kompatibilita verze serveru

​Automatizované CI/CD (předpřipravené workflowy)

​CI — ci.yml

​CD — cd.yml

​Publish — publish.yml

​Připnutí verzí znovupoužitelných akcí

​Publikování na npm

​Požadavky

​Metadata tržiště

​Doporučené rozměry obrázků v galerii

​Limit velikosti obrázku

​Publikování

​Jak funguje objevování v tržišti

​Publikování pomocí CI

​Instalace aplikací

Přehled

Sestavení vaší aplikace

Nasazení na server (tarball)

Předpoklady

Nasazení

Sdílení nasazené aplikace

Správa verzí

Kompatibilita verze serveru

Automatizované CI/CD (předpřipravené workflowy)

CI — `ci.yml`

CD — `cd.yml`

Publish — `publish.yml`

Připnutí verzí znovupoužitelných akcí

Publikování na npm

Požadavky

Metadata tržiště

Doporučené rozměry obrázků v galerii

Limit velikosti obrázku

Publikování

Jak funguje objevování v tržišti

Publikování pomocí CI

Instalace aplikací