Publicare

Prezentare generală

După ce aplicația ta este construită și testată local, ai două căi pentru distribuire:

Implementează un tarball — încarcă aplicația direct pe un server Twenty anume pentru uz intern sau privat.
Publică pe npm — listează aplicația ta în marketplace-ul Twenty pentru ca orice spațiu de lucru să o poată descoperi și instala.

Ambele căi pornesc din aceeași etapă de build.

Construirea aplicației

Rulează comanda build pentru a compila aplicația și a genera un manifest.json pregătit pentru distribuire:

yarn twenty dev:build

Aceasta compilează sursele TypeScript, transpilează funcțiile de logică și componentele de front-end și scrie totul în .twenty/output/. Adaugă --tarball pentru a produce și un pachet .tgz pentru distribuire manuală sau pentru comanda de publish.

Implementare pe un server (tarball)

Pentru aplicațiile pe care nu le dorești disponibile public — instrumente proprietare, integrări doar pentru enterprise sau build-uri experimentale — poți implementa un tarball direct pe un server Twenty.

Cerințe

Înainte de implementare, ai nevoie de un remote configurat care să indice serverul țintă. Remote-urile stochează local URL-ul serverului și credențialele de autentificare în ~/.twenty/config.json. Adaugă un remote:

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

Implementare

Construiește și încarcă aplicația ta pe server într-un singur pas:

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

Partajarea unei aplicații implementate

Aplicațiile tarball nu sunt listate în marketplace-ul public, astfel încât alte spații de lucru de pe același server nu le vor descoperi prin navigare. Pentru a partaja o aplicație implementată:

Mergi la Setări > Aplicații > Înregistrări și deschide aplicația ta
În fila Distribuție, fă clic pe Copiază linkul de partajare
Partajează acest link cu utilizatori din alte spații de lucru — îi duce direct la pagina de instalare a aplicației

Linkul de partajare folosește URL-ul de bază al serverului (fără niciun subdomeniu de spațiu de lucru), astfel încât funcționează pentru orice spațiu de lucru de pe server.

Gestionarea versiunilor

Când actualizezi o aplicație tarball deja implementată, serverul solicită ca version din package.json să fie strict mai mare (conform ordonării semver) decât versiunea implementată în prezent. Redeployarea aceleiași versiuni sau trimiterea uneia inferioare este respinsă înainte ca tarball-ul să fie stocat — vei vedea o eroare VERSION_ALREADY_EXISTS de la CLI. Pentru a lansa o actualizare:

Incrementează câmpul version din package.json (de ex. 1.2.3 → 1.2.4, 1.3.0 sau 2.0.0)
Rulează yarn twenty app:publish --private (sau yarn twenty app:publish --private --remote production)
Spațiile de lucru care au aplicația instalată și au activat actualizarea automată pentru aceasta (în fila Setări a aplicației) sunt actualizate automat în fundal; celelalte vor vedea actualizarea disponibilă în setările lor

Etichetele de pre-lansare funcționează conform așteptărilor: incrementarea de la 1.0.0-rc.1 la 1.0.0-rc.2 este permisă, iar o lansare finală precum 1.0.0 este recunoscută corect ca fiind mai mare decât 1.0.0-rc.5. Versiunea din package.json trebuie să fie ea însăși un șir semver valid.

Compatibilitatea versiunii serverului

Dacă aplicația ta folosește o funcționalitate introdusă într-o anumită versiune de server Twenty (de exemplu, furnizori OAuth adăugați în v2.3.0), ar trebui să declari versiunea minimă de server necesară aplicației folosind câmpul engines.twenty din package.json:

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

Valoarea este un interval semver standard. Tipare comune:

Interval	Semnificație
`>=2.3.0`	Orice server de la 2.3.0 încolo
`>=2.3.0 \<3.0.0`	2.3.0 sau ulterior, dar sub următoarea versiune majoră
`^2.3.0`	La fel ca `>=2.3.0 \<3.0.0`

Ce se întâmplă în timpul implementării și instalării:

Dacă engines.twenty este setat și versiunea serverului țintă nu respectă intervalul, implementarea (încărcarea arhivei tarball) sau instalarea este respinsă cu eroarea SERVER_VERSION_INCOMPATIBLE și cu un mesaj care indică atât intervalul necesar, cât și versiunea efectivă a serverului.
Dacă engines.twenty nu este setat, aplicația este acceptată pe orice versiune de server (retrocompatibilă cu aplicațiile existente).
Dacă serverul nu are nicio APP_VERSION configurată, verificarea este omisă.

Serverul este verificarea autoritativă — validează engines.twenty atât la încărcarea arhivei tarball, cât și la instalarea în spațiul de lucru. Dacă implementezi un tarball în afara fluxului standard sau instalezi din marketplace, serverul impune în continuare compatibilitatea.

CI/CD automatizat (fluxuri de lucru preconfigurate)

Aplicațiile generate cu create-twenty-app vin, gata de utilizare, cu trei fluxuri de lucru GitHub Actions, în .github/workflows/. CI rulează fără nicio configurare, CD necesită un singur secret, iar publicarea pe npm necesită o configurare unică pentru npm trusted publisher.

CI — `ci.yml`

Rulează testele de integrare la fiecare push pe main și la fiecare pull request. Ce face:

Preia codul sursă al aplicației.
Pornește o instanță de test Twenty izolată folosind acțiunea compozită twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main (echivalentul din CI al yarn twenty docker:start --test).
Activează Corepack, configurează Node.js pe baza fișierului .nvmrc și instalează dependențele cu yarn install --immutable.
Rulează yarn test, transmitând TWENTY_API_URL și TWENTY_API_KEY din instanța pornită, astfel încât testele să poată comunica cu un server real.

Opțiuni de configurare:

TWENTY_VERSION (variabilă de mediu, implicit latest) — fixează versiunea serverului Twenty folosită în CI editând acest parametru în ci.yml.
Concurența este grupată după github.ref și anulează execuțiile în desfășurare la noile push-uri.

Nu sunt necesare secrete — instanța de test este efemeră și există doar pe durata jobului.

CD — `cd.yml`

Implementează aplicația pe un server Twenty configurat la fiecare push pe main și, opțional, dintr-un pull request când se aplică eticheta deploy. Ce face:

Preia head-ul PR-ului (pentru PR-urile etichetate) sau commitul împins.
Rulează twentyhq/twenty/.github/actions/deploy-twenty-app@main — echivalentul din CI al yarn twenty app:publish --private.
Rulează twentyhq/twenty/.github/actions/install-twenty-app@main astfel încât versiunea nou implementată să fie instalată în spațiul de lucru țintă.

Configurare necesară:

Setare	Unde	Scop
`TWENTY_DEPLOY_URL`	`env` în `cd.yml` (implicit `http://localhost:3000`)	Serverul Twenty la care se face implementarea. Modifică-l la URL-ul real al serverului înainte de prima utilizare.
`TWENTY_DEPLOY_API_KEY`	GitHub repo Settings → Secrets and variables → Actions	Cheie API cu permisiune de implementare pe serverul țintă.

Valoarea implicită a TWENTY_DEPLOY_URL, http://localhost:3000, este un placeholder — nu va putea accesa nimic dintr-un runner găzduit de GitHub. Actualizează-l la URL-ul public al serverului tău (sau folosește un runner self-hosted cu acces la rețea) înainte de a activa CD.

Declanșarea unei implementări de previzualizare dintr-un PR: Adaugă eticheta deploy la un pull request. Condiția if: din cd.yml va rula jobul pentru acel PR folosind commitul head al PR-ului, permițându-ți să validezi o modificare pe serverul țintă înainte de a face merge.

Publicare — `publish.yml`

Publică aplicația pe npm, cu proveniență, când împingi un tag de versiune (de ex. v1.0.0) sau când rulezi manual fluxul de lucru din fila Actions. Ce face:

Face checkout al aplicației tale, configurează Node.js și actualizează npm (publicarea de încredere necesită npm 11.5.1 sau o versiune ulterioară).
Rulează yarn twenty app:publish, care construiește aplicația și publică .twenty/output în npm. În CI adaugă automat --provenance și --access public, astfel încât nu sunt necesare flaguri în fluxul de lucru.

Configurare unică: Pe npmjs.com deschide pachetul tău > Settings → Trusted Publisher și înregistrează acest repozitoriu cu fluxul de lucru publish.yml (vezi documentația npm trusted publishing). Publicarea cu provenance certifică ce repozitoriu GitHub a construit pachetul, ceea ce este, de asemenea, modul în care îți revendici proprietatea asupra aplicației tale într-un marketplace Twenty.

npm acceptă doar proveniență din depozite sursă publice. Dacă publici dintr-un depozit privat, npm respinge pachetul de proveniență OIDC cu un E422 ... Eroare „Unsupported GitHub Actions source repository visibility: "private".” Pentru a publica dintr-un depozit privat, renunță la proveniență setând TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true' în env al etapei de publicare (un indiciu comentat este inclus în fișierul generat publish.yml):

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

Fixarea acțiunilor reutilizabile

Fluxurile de lucru ci.yml și cd.yml fac referire la acțiuni reutilizabile la @main, astfel încât actualizările acțiunilor din repo-ul twentyhq/twenty sunt preluate automat. Dacă dorești builduri deterministe, înlocuiește @main cu un SHA de commit sau cu un tag de release pe fiecare linie uses:.

Publicarea pe npm

Publicarea pe npm face ca aplicația ta să poată fi descoperită în marketplace-ul Twenty. Orice spațiu de lucru Twenty poate răsfoi, instala și actualiza aplicațiile din marketplace direct din interfață.

Cerințe

Un cont npm
Cuvântul cheie twenty-app din array-ul keywords al fișierului package.json (adaugă-l manual — nu este inclus în mod implicit în șablonul create-twenty-app)

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

Metadate pentru marketplace

Configurația defineApplication() acceptă câmpuri opționale care controlează modul în care aplicația ta apare în marketplace. Folosește logo și galleryImages pentru a face referire la imaginile din folderul 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',
  ],
});

Vezi acordeonul defineApplication din pagina Building Apps pentru lista completă de câmpuri ale marketplace-ului (author, category, aboutDescription, websiteUrl, termsUrl, etc.).

Dimensiuni recomandate pentru imaginile din galerie

Marketplace-ul redă galleryImages într-un container fix cu raport 8:5 (de exemplu, 1600×1000 px).

Imaginile din galerie cu orice raport de aspect sunt afișate integral și nu sunt niciodată decupate, însă orice imagine semnificativ mai înaltă sau mai îngustă decât 8:5 va afișa benzi goale pe laterale.

Limită de dimensiune pentru imagini

Fișierul logo și fiecare fișier din galleryImages nu trebuie să depășească 10 MB. Fișierele mai mari sunt omise atunci când marketplace-ul re-găzduiește resursele tale publicate, astfel că nu vor fi afișate.

yarn twenty app:publish

Pentru a publica sub un dist-tag specific (de ex., beta sau next):

yarn twenty app:publish --tag beta

Cum funcționează descoperirea în marketplace

Serverul Twenty sincronizează catalogul marketplace-ului din registrul npm la fiecare oră. Poți declanșa sincronizarea imediat, în loc să aștepți:

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

Metadatele afișate în marketplace provin din configurația defineApplication() — vezi secțiunea Metadate pentru marketplace de mai sus.

Dacă aplicația ta nu definește un aboutDescription în defineApplication(), piața va folosi automat fișierul README.md al pachetului tău de pe npm drept conținut pentru pagina Despre. Acest lucru înseamnă că poți menține un singur README atât pentru npm, cât și pentru piața Twenty. Dacă vrei o descriere diferită în piață, setează explicit aboutDescription.

Publicare CI

Fluxul de lucru generat publish.yml descris mai sus publică automat pe npm la etichetele de versiune, cu provenance. Deoarece yarn twenty app:publish adaugă --provenance și --access public pentru tine când rulează în CI, fluxul de lucru nu are nevoie de flaguri npm — doar de configurarea unică a Trusted Publisher. Pentru alte sisteme CI (GitLab CI, CircleCI etc.), rulează yarn install apoi yarn twenty app:publish. Provenance este emisă atunci când mediul poate genera un token OIDC și este omisă automat în caz contrar.

npm provenance adaugă un badge de încredere la listarea ta în npm, permițând utilizatorilor să verifice că pachetul a fost construit dintr-un commit specific într-un pipeline CI public. Este, de asemenea, ceea ce îți permite să revendici proprietatea asupra aplicației tale într-un marketplace Twenty. Vezi documentația npm provenance pentru detalii.

Instalarea aplicațiilor

După ce o aplicație este publicată (npm) sau implementată (tarball), spațiile de lucru o pot instala prin interfața utilizatorului (UI). Mergi la pagina Setări > Aplicații din Twenty, unde pot fi parcurse și instalate atât aplicațiile din marketplace, cât și cele implementate prin tarball. Poți instala aplicații și din linia de comandă:

yarn twenty app:install

Serverul impune versionarea semver la instalare, reflectând regulile de la deploy:

Instalarea aceleiași versiuni care este deja instalată în spațiul tău de lucru este respinsă cu o eroare APP_ALREADY_INSTALLED.
Instalarea unei versiuni mai mici decât cea instalată în prezent este respinsă cu o eroare CANNOT_DOWNGRADE_APPLICATION.

Pentru a instala o versiune mai nouă, fă mai întâi deploy sau public-o, apoi rulează din nou yarn twenty app:install.

Prezentare generală

Aplicații

API

Autogazda

Contribuie

Publicare

Prezentare generală

Construirea aplicației

Implementare pe un server (tarball)

Cerințe

Implementare

Partajarea unei aplicații implementate

Gestionarea versiunilor

Compatibilitatea versiunii serverului

CI/CD automatizat (fluxuri de lucru preconfigurate)

CI — `ci.yml`

CD — `cd.yml`

Publicare — `publish.yml`

Fixarea acțiunilor reutilizabile

Publicarea pe npm

Cerințe

Metadate pentru marketplace

Dimensiuni recomandate pentru imaginile din galerie

Limită de dimensiune pentru imagini

Publicare

Cum funcționează descoperirea în marketplace

Publicare CI

Instalarea aplicațiilor

​Prezentare generală

​Construirea aplicației

​Implementare pe un server (tarball)

​Cerințe

​Implementare

​Partajarea unei aplicații implementate

​Gestionarea versiunilor

​Compatibilitatea versiunii serverului

​CI/CD automatizat (fluxuri de lucru preconfigurate)

​CI — ci.yml

​CD — cd.yml

​Publicare — publish.yml

​Fixarea acțiunilor reutilizabile

​Publicarea pe npm

​Cerințe

​Metadate pentru marketplace

​Dimensiuni recomandate pentru imaginile din galerie

​Limită de dimensiune pentru imagini

​Publicare

​Cum funcționează descoperirea în marketplace

​Publicare CI

​Instalarea aplicațiilor

Prezentare generală

Construirea aplicației

Implementare pe un server (tarball)

Cerințe

Implementare

Partajarea unei aplicații implementate

Gestionarea versiunilor

Compatibilitatea versiunii serverului

CI/CD automatizat (fluxuri de lucru preconfigurate)

CI — `ci.yml`

CD — `cd.yml`

Publicare — `publish.yml`

Fixarea acțiunilor reutilizabile

Publicarea pe npm

Cerințe

Metadate pentru marketplace

Dimensiuni recomandate pentru imaginile din galerie

Limită de dimensiune pentru imagini

Publicare

Cum funcționează descoperirea în marketplace

Publicare CI

Instalarea aplicațiilor