274 lines
15 KiB
Plaintext
274 lines
15 KiB
Plaintext
---
|
|
title: Începeți
|
|
icon: rocket
|
|
description: Creați prima dvs. aplicație Twenty în câteva minute.
|
|
---
|
|
|
|
## Cerințe
|
|
|
|
* **Node.js 24+** — [Descărcați](https://nodejs.org/)
|
|
* **Yarn 4** — vine împreună cu Node prin Corepack. Activați-l: `corepack enable`
|
|
* **Docker** — [Descărcați](https://www.docker.com/products/docker-desktop/). 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:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Vi se va cere un nume și o descriere — apăsați **Enter** pentru valorile implicite. Aceasta generează un proiect TypeScript în `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`.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Porniți instanța locală?" />
|
|
</div>
|
|
|
|
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`
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Ecranul de autentificare Twenty" />
|
|
</div>
|
|
|
|
Faceți clic pe **Authorize** pe ecranul următor — aceasta oferă CLI-ului acces la spațiul dvs. de lucru.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Ecranul de autorizare Twenty CLI" />
|
|
</div>
|
|
|
|
Terminalul va confirma că totul este configurat.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Aplicația a fost creată cu succes" />
|
|
</div>
|
|
|
|
**După această fază:** aveți un server Twenty care rulează la [http://localhost:2020](http://localhost:2020), iar CLI-ul dvs. este autorizat să sincronizeze cu acesta.
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Faza 3 — Sincronizați modificările
|
|
|
|
Aceasta este bucla internă în care veți petrece cea mai mare parte a timpului.
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
Aceasta monitorizează `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`.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.png" alt="Ieșirea terminalului în modul de dezvoltare" />
|
|
</div>
|
|
|
|
Deschideți [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Ar trebui să vedeți aplicația dvs. listată la **Your Apps**.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Lista Your Apps care afișează My twenty app" />
|
|
</div>
|
|
|
|
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.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Detalii despre înregistrarea aplicației" />
|
|
</div>
|
|
|
|
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.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Aplicație instalată" />
|
|
</div>
|
|
|
|
**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:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --once
|
|
```
|
|
|
|
| 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. |
|
|
|
|
Ambele moduri necesită un server în modul de dezvoltare și un remote autentificat.
|
|
|
|
<Warning>
|
|
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](/l/ro/developers/extend/apps/publishing).
|
|
</Warning>
|
|
|
|
---
|
|
|
|
## 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 |
|
|
|
|
Referință completă: [Crearea aplicațiilor](/l/ro/developers/extend/apps/building).
|
|
|
|
## Structura proiectului
|
|
|
|
```text filename="my-twenty-app/"
|
|
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):
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Exemplele se află în [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples). Puteți, de asemenea, să creați scheletul entităților individuale într-un proiect existent cu `yarn twenty add` — vedeți [Crearea aplicațiilor](/l/ro/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add).
|
|
|
|
---
|
|
|
|
## 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ă |
|
|
|
|
Datele persistă între reporniri în două volume Docker (`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.
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server upgrade # Latest
|
|
yarn twenty server upgrade 2.2.0 # Specific version
|
|
```
|
|
|
|
Puteți verifica versiunea care rulează cu `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 |
|
|
|
|
Instanța de test are propriul container (`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:
|
|
|
|
```bash filename="Terminal"
|
|
yarn add twenty-sdk twenty-client-sdk
|
|
```
|
|
|
|
Adăugați scriptul în `package.json`:
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Acum puteți rula `yarn twenty dev`, `yarn twenty server start` și restul.
|
|
|
|
<Note>
|
|
Nu instalați `twenty-sdk` global — fixați-l per proiect astfel încât fiecare aplicație să folosească propria versiune.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## 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](https://discord.com/channels/1130383047699738754/1130386664812982322).
|