Cerințe
- Node.js 24+ — Descărcați
- Yarn 4 — vine împreună cu Node prin Corepack. Activați-l:
corepack enable
- Docker — Descărcați. Necesar pentru a rula un server Twenty local. Omiteți dacă rulați deja Twenty în altă parte.
Crearea unei aplicații Twenty are trei faze. Generatorul de schelet le reduce la o singură comandă pe happy path, dar fiecare fază este un concept separat — când ceva eșuează, dacă știți în ce fază sunteți, știți ce trebuie să corectați.
| Fază | Ce faceți | Instrument | Rezultat |
|---|
| 1. Creați scheletul | Generați codul sursă al aplicației | npx create-twenty-app | Un proiect TypeScript pe disc |
| 2. Rulați un server | Porniți un server Twenty cu care să sincronizați | Docker + yarn twenty server | O instanță Twenty care rulează |
| 3. Sincronizați | Sincronizați în timp real codul cu serverul | yarn twenty dev | Modificările apar în UI |
Faza 1 — Creați scheletul proiectului
Creați o nouă aplicație din șablon:
npx create-twenty-app@latest my-twenty-app
my-twenty-app/ cu un fișier inițial application-config.ts, un rol implicit, un flux de lucru CI și un test de integrare.
După această fază: aveți codul sursă al aplicației pe mașina dvs. Încă nu rulează — aceasta este Faza 2.
Faza 2 — Rulați un server Twenty local
Aplicația are nevoie de un server Twenty cu care să se sincronizeze. Serverul este o instanță Twenty completă — UI, API GraphQL, PostgreSQL — care rulează local în Docker. Codul local încarcă definițiile pe acel server, făcându-le să apară în UI.
Generatorul de schelet vă propune să pornească unul pentru dvs.:
Doriți să configurați o instanță Twenty locală?
- Yes (recomandat) — descarcă imaginea Docker
twentycrm/twenty-app-dev și o pornește pe portul 2020. Asigurați-vă mai întâi că Docker rulează.
- No — alegeți această opțiune dacă aveți deja un server Twenty la care doriți să vă conectați. Îl puteți conecta ulterior cu
yarn twenty remote add.
După ce serverul pornește, se deschide un browser pentru autentificare. Folosiți contul demo preconfigurat:
- E-mail:
tim@apple.dev
- Parolă:
tim@apple.dev
Faceți clic pe Authorize pe ecranul următor — aceasta oferă CLI-ului acces la spațiul dvs. de lucru.
Terminalul va confirma că totul este configurat.
După această fază: aveți un server Twenty care rulează la http://localhost:2020, iar CLI-ul dvs. este autorizat să sincronizeze cu acesta.
Dacă Docker nu este instalat sau nu rulează, generatorul de schelet vă va indica comanda corectă de pornire pentru sistemul dvs. de operare. După ce Docker rulează, puteți continua cu yarn twenty server start — nu este nevoie să recreați scheletul.
Faza 3 — Sincronizați modificările
Aceasta este bucla internă în care veți petrece cea mai mare parte a timpului.
cd my-twenty-app
yarn twenty dev
src/, reconstruiește la fiecare modificare și sincronizează rezultatul pe server. Editați un fișier, salvați, iar în decurs de o secundă serverul reflectă modificarea. Veți vedea în terminal un panou de stare în timp real.
Pentru un output mai detaliat (jurnale de build, cereri de sincronizare, urme ale erorilor), adăugați --verbose.
Deschideți http://localhost:2020/settings/applications#developer. Ar trebui să vedeți aplicația dvs. listată la Your Apps.
Faceți clic pe My twenty app pentru a vedea înregistrarea aplicației — o înregistrare la nivel de server care descrie aplicația dvs. (nume, identificator, credențiale OAuth, sursă). O singură înregistrare poate fi instalată în mai multe spații de lucru pe același server.
Faceți clic pe View installed app pentru a vedea instalarea în spațiul de lucru. Fila About afișează versiunea și opțiunile de administrare.
După această fază: aveți o buclă de dezvoltare în timp real. Editați orice fișier în src/ și acesta apare în UI.
Sincronizare unică pentru CI și scripturi
Adăugați --once pentru a rula un singur build + sync și a ieși — același flux, fără watcher:
| Comandă | Comportament | Când se folosește |
|---|
yarn twenty dev | Monitorizează și resincronizează la fiecare modificare. Rulează până când îl opriți. | Dezvoltare locală interactivă. |
yarn twenty dev --once | Un singur build + sync, iese cu 0 la succes, 1 la eșec. | CI, hook-uri pre-commit, agenți AI, fluxuri de lucru scriptate. |
Modul de dezvoltare este disponibil doar pe instanțele Twenty care rulează în modul development (NODE_ENV=development). Instanțele de producție resping cererile de sincronizare din modul de dezvoltare — folosiți yarn twenty deploy pentru a implementa pe serverele de producție. Consultați Publicarea aplicațiilor.
Ce puteți construi
Aplicațiile sunt compuse din entități — fiecare definită într-un fișier TypeScript cu un singur export default:
| Entitate | Ce face |
|---|
| Obiecte și câmpuri | Modele de date personalizate (carte poștală, factură etc.) cu câmpuri tipizate |
| Funcții logice | TypeScript pe server declanșat de rute HTTP, programări cron sau evenimente din baza de date |
| Componente front-end | Componente React care se afișează în UI-ul Twenty (panou lateral, widgeturi, meniul de comenzi) |
| Abilități și agenți | Capabilități AI — instrucțiuni reutilizabile și asistenți autonomi |
| Vizualizări și navigare | Vizualizări de listă preconfigurate și elemente de meniu în bara laterală |
| Layouturi de pagină | Pagini personalizate de detalii ale înregistrărilor cu file și widgeturi |
Structura proiectului
my-twenty-app/
package.json
src/
application-config.ts # Required — your app's entry point
default-role.ts # Permissions for logic functions
constants/
universal-identifiers.ts # Auto-generated UUIDs and metadata
__tests__/
setup-test.ts
app-install.integration-test.ts
.github/workflows/ci.yml # GitHub Actions
public/ # Static assets
vitest.config.ts # Test runner config
tsconfig.json, tsconfig.spec.json
.nvmrc, .yarnrc.yml, .oxlintrc.json
README.md, LLMS.md
| Fișier / Folder | Scop |
|---|
src/application-config.ts | Necesar. Fișierul principal de configurare pentru aplicație. |
src/default-role.ts | Rol implicit care controlează la ce pot avea acces funcțiile logice. |
src/constants/universal-identifiers.ts | UUID-uri generate automat și metadate (nume afișat, descriere). |
src/__tests__/ | Teste de integrare (configurare + test exemplu). |
public/ | Resurse statice (imagini, fonturi) servite împreună cu aplicația. |
Pornind de la un exemplu
Folosiți --example pentru a începe cu un proiect mai complet (obiecte personalizate, câmpuri, funcții logice, componente front-end):
npx create-twenty-app@latest my-twenty-app --example postcard
yarn twenty add — vedeți Crearea aplicațiilor.
Gestionarea serverului local
Folosiți yarn twenty server pentru a controla containerul Twenty local:
| Comandă | Ce face |
|---|
yarn twenty server start | Pornește serverul (descarcă imaginea dacă este necesar) |
yarn twenty server start --port 3030 | Pornește pe un port personalizat |
yarn twenty server stop | Oprește serverul (păstrează datele) |
yarn twenty server status | Afișează URL-ul, versiunea și credențialele de autentificare |
yarn twenty server logs | Transmite în flux jurnalele serverului |
yarn twenty server reset | Șterge datele și pornește de la zero |
yarn twenty server upgrade | Descarcă cea mai recentă imagine twenty-app-dev |
yarn twenty server upgrade 2.2.0 | Actualizează la o versiune specifică |
twenty-app-dev-data pentru PostgreSQL, twenty-app-dev-storage pentru fișiere). Folosiți reset pentru a șterge totul.
Actualizarea imaginii serverului
yarn twenty server upgrade descarcă cea mai recentă imagine, compară digest-urile și recreează containerul doar dacă s-a schimbat ceva. Volumele de date sunt păstrate — doar containerul este înlocuit. Dacă a fost descărcată o imagine nouă și containerul rula, actualizarea pornește automat un container nou; rulați apoi yarn twenty server start pentru a aștepta până când devine funcțional.
yarn twenty server upgrade # Latest
yarn twenty server upgrade 2.2.0 # Specific version
yarn twenty server status (aceasta afișează APP_VERSION încorporat în container).
Rularea unei instanțe de test în paralel
Adăugați --test la orice comandă server pentru a gestiona o a doua instanță, complet izolată — utilă pentru teste de integrare sau pentru a experimenta fără a atinge datele principale de dezvoltare:
| Comandă | Ce face |
|---|
yarn twenty server start --test | Pornește instanța de test (implicit pe portul 2021) |
yarn twenty server stop --test | Opriți-o |
yarn twenty server status --test | Afișați-i starea |
yarn twenty server logs --test | Transmiteți în flux jurnalele sale |
yarn twenty server reset --test | Ștergeți-i datele |
yarn twenty server upgrade --test | Actualizați-i imaginea |
twenty-app-dev-test), propriile volume (twenty-app-dev-test-data, twenty-app-dev-test-storage) și propria configurație — rulează alături de instanța principală, fără conflicte. Combinați --test cu --port pentru a înlocui portul 2021.
Configurare manuală (fără generator)
Săriți peste generatorul de schelet dacă adăugați SDK-ul într-un proiect existent:
yarn add twenty-sdk twenty-client-sdk
package.json:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty server start și restul.
Nu instalați twenty-sdk global — fixați-l per proiect astfel încât fiecare aplicație să folosească propria versiune.
Depanare
- Erori Docker — Asigurați-vă că Docker Desktop (sau daemonul) rulează înainte de
yarn twenty server start. Mesajul de eroare va afișa comanda corectă de pornire pentru sistemul dvs. de operare.
- Versiune Node greșită — Aveți nevoie de 24+. Verificați cu
node -v.
- Lipsește Yarn 4 — Rulați
corepack enable.
- Dependențe nefuncționale —
rm -rf node_modules && yarn install.
Blocat? Întrebați pe Discordul Twenty.
