412 lines
19 KiB
Plaintext
412 lines
19 KiB
Plaintext
---
|
|
title: Începeți
|
|
description: Creați prima dvs. aplicație Twenty în câteva minute.
|
|
---
|
|
|
|
<Warning>
|
|
Aplicațiile sunt în prezent în testare alfa. Caracteristica funcționează, dar este încă în dezvoltare.
|
|
</Warning>
|
|
|
|
Aplicațiile vă permit să extindeți Twenty cu obiecte personalizate, câmpuri, funcții logice, abilități IA și componente UI — toate gestionate ca cod.
|
|
|
|
## Cerințe
|
|
|
|
Înainte de a începe, asigurați-vă că următoarele sunt instalate pe calculatorul dvs.:
|
|
|
|
* **Node.js 24+** — [Descărcați aici](https://nodejs.org/)
|
|
* **Yarn 4** — Vine împreună cu Node.js prin Corepack. Activați-l rulând `corepack enable`
|
|
* **Docker** — [Descărcați aici](https://www.docker.com/products/docker-desktop/). Necesar pentru a rula o instanță Twenty locală. Nu este necesar dacă aveți deja un server Twenty care rulează.
|
|
|
|
## Pasul 1: Creați scheletul aplicației
|
|
|
|
Deschideți un terminal și rulați:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Vi se va cere să introduceți un nume și o descriere pentru aplicația dvs. Apăsați **Enter** pentru a accepta valorile implicite.
|
|
|
|
Aceasta creează un folder nou numit `my-twenty-app` cu tot ce aveți nevoie.
|
|
|
|
<Note>
|
|
Generatorul de schelet acceptă următoarele opțiuni:
|
|
|
|
* `--minimal` — generează doar fișierele esențiale, fără exemple (implicit)
|
|
* `--exhaustive` — generează toate entitățile de exemplu
|
|
* `--name <name>` — setează numele aplicației (omite solicitarea)
|
|
* `--display-name <displayName>` — setează numele afișat (omite solicitarea)
|
|
* `--description <description>` — setează descrierea (omite solicitarea)
|
|
* `--skip-local-instance` — omite solicitarea de configurare a serverului local
|
|
</Note>
|
|
|
|
## Pasul 2: Configurați o instanță Twenty locală
|
|
|
|
Generatorul de schelet va întreba:
|
|
|
|
> **Doriți să configurați o instanță Twenty locală?**
|
|
|
|
* **Tastați `yes`** (recomandat) — Aceasta descarcă imaginea Docker `twenty-app-dev` și pornește un server Twenty local pe portul `2020`. Asigurați-vă că Docker rulează înainte de a continua.
|
|
* **Tastați `no`** — Alegeți această opțiune dacă aveți deja un server Twenty care rulează local.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Porniți instanța locală?" />
|
|
</div>
|
|
|
|
## Pasul 3: Autentificați-vă în spațiul dvs. de lucru
|
|
|
|
În continuare, se va deschide o fereastră de browser cu pagina de autentificare Twenty. Autentificați-vă cu 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>
|
|
|
|
## Pasul 4: Autorizați aplicația
|
|
|
|
După autentificare, veți vedea un ecran de autorizare. Acest lucru permite aplicației dvs. să interacționeze cu spațiul dvs. de lucru.
|
|
|
|
Faceți clic pe **Authorize** pentru a continua.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Ecranul de autorizare Twenty CLI" />
|
|
</div>
|
|
|
|
După autorizare, 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>
|
|
|
|
## Pasul 5: Începeți dezvoltarea
|
|
|
|
Intrați în noul folder al aplicației și porniți serverul de dezvoltare:
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
Acesta monitorizează fișierele sursă, reconstruiește la fiecare modificare și sincronizează automat aplicația cu serverul Twenty local. Ar trebui să vedeți în terminal un panou de stare în timp real.
|
|
|
|
Pentru un output mai detaliat (jurnale de build, cereri de sincronizare, urme ale erorilor), folosiți opțiunea `--verbose`:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --verbose
|
|
```
|
|
|
|
<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 pentru dezvoltare. Folosiți `yarn twenty deploy` pentru a implementa pe serverele de producție — vedeți [Publicarea aplicațiilor](/l/ro/developers/extend/apps/publishing) pentru detalii.
|
|
</Warning>
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Ieșirea terminalului în modul de dezvoltare" />
|
|
</div>
|
|
|
|
## Pasul 6: Vedeți aplicația în Twenty
|
|
|
|
Deschideți [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) în browser. Navigați la **Settings > Apps** și selectați fila **Developer**. Ar trebui să vedeți aplicația 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 deschide **înregistrarea aplicației**. O înregistrare este un element la nivel de server care descrie aplicația — numele, identificatorul unic, acreditările OAuth și sursa (locală, npm sau arhivă tar). Aceasta există pe server, nu în interiorul unui spațiu de lucru anume. Când instalați o aplicație într-un spațiu de lucru, Twenty creează o aplicație la nivelul spațiului de lucru care face referire la această înregistrare. 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 aplicația instalată. Fila **About** afișează versiunea curentă ș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ă — fila About" />
|
|
</div>
|
|
|
|
Comutați la fila **Content** pentru a vedea tot ceea ce oferă aplicația — obiecte, câmpuri, funcții logice și agenți:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Aplicație instalată — fila Content" />
|
|
</div>
|
|
|
|
Totul este gata! Editați orice fișier din `src/`, iar modificările vor fi preluate automat.
|
|
|
|
Accesați [Construirea aplicațiilor](/l/ro/developers/extend/apps/building) pentru un ghid detaliat despre crearea de obiecte, funcții logice, componente front-end, abilități și altele.
|
|
|
|
---
|
|
|
|
## Structura proiectului
|
|
|
|
Generatorul de schelet generează următoarea structură de fișiere (afișată cu modul `--exhaustive`, care include exemple pentru fiecare tip de entitate):
|
|
|
|
```text filename="my-twenty-app/"
|
|
my-twenty-app/
|
|
package.json
|
|
yarn.lock
|
|
.gitignore
|
|
.nvmrc
|
|
.yarnrc.yml
|
|
.yarn/
|
|
install-state.gz
|
|
.oxlintrc.json
|
|
tsconfig.json
|
|
tsconfig.spec.json # TypeScript config for tests
|
|
vitest.config.ts # Vitest test runner configuration
|
|
LLMS.md
|
|
README.md
|
|
.github/
|
|
└── workflows/
|
|
└── ci.yml # GitHub Actions CI workflow
|
|
public/ # Public assets (images, fonts, etc.)
|
|
src/
|
|
├── application-config.ts # Required — main application configuration
|
|
├── __tests__/
|
|
│ ├── setup-test.ts # Test setup (server health check, config)
|
|
│ └── app-install.integration-test.ts # Example integration test
|
|
├── roles/
|
|
│ └── default-role.ts # Default role for logic functions
|
|
├── objects/
|
|
│ └── example-object.ts # Example custom object definition
|
|
├── fields/
|
|
│ └── example-field.ts # Example standalone field definition
|
|
├── logic-functions/
|
|
│ ├── hello-world.ts # Example logic function
|
|
│ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
|
|
│ ├── pre-install.ts # Runs before installation
|
|
│ └── post-install.ts # Runs after installation
|
|
├── front-components/
|
|
│ └── hello-world.tsx # Example front component
|
|
├── page-layouts/
|
|
│ └── example-record-page-layout.ts # Example page layout with front component
|
|
├── views/
|
|
│ └── example-view.ts # Example saved view definition
|
|
├── navigation-menu-items/
|
|
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
|
|
├── skills/
|
|
│ └── example-skill.ts # Example AI agent skill definition
|
|
└── agents/
|
|
└── example-agent.ts # Example AI agent definition
|
|
```
|
|
|
|
În mod implicit (`--minimal`), sunt create doar fișierele de bază: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` și `logic-functions/post-install.ts`. Folosiți `--exhaustive` pentru a include toate fișierele de exemplu prezentate mai sus.
|
|
|
|
### Fișiere cheie
|
|
|
|
| Fișier / Folder | Scop |
|
|
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `package.json` | Declară numele aplicației, versiunea și dependențele. Include un script `twenty` astfel încât să puteți rula `yarn twenty help` pentru a vedea toate comenzile. |
|
|
| `src/application-config.ts` | **Necesar.** Fișierul principal de configurare pentru aplicație. |
|
|
| `src/roles/` | Definește roluri care controlează la ce pot avea acces funcțiile logice. |
|
|
| `src/logic-functions/` | Funcții pe server declanșate de rute, programări cron sau evenimente din baza de date. |
|
|
| `src/front-components/` | Componente React care se afișează în interfața Twenty. |
|
|
| `src/objects/` | Definiții de obiecte personalizate pentru a extinde modelul de date. |
|
|
| `src/fields/` | Câmpuri personalizate adăugate obiectelor existente. |
|
|
| `src/views/` | Configurații pentru vizualizări salvate. |
|
|
| `src/navigation-menu-items/` | Linkuri personalizate în bara laterală de navigare. |
|
|
| `src/skills/` | Abilități care extind capabilitățile agenților AI ai Twenty. |
|
|
| `src/agents/` | Agenți AI cu prompturi personalizate. |
|
|
| `src/page-layouts/` | Machete de pagină personalizate pentru vizualizările de înregistrare. |
|
|
| `src/__tests__/` | Teste de integrare (configurare + test exemplu). |
|
|
| `public/` | Resurse statice (imagini, fonturi) servite împreună cu aplicația. |
|
|
|
|
## Gestionarea remote-urilor
|
|
|
|
Un „remote” este un server Twenty la care se conectează aplicația. În timpul configurării, generatorul de schelet creează automat unul pentru dvs. Puteți adăuga mai multe remote-uri sau comuta între ele oricând.
|
|
|
|
```bash filename="Terminal"
|
|
# Add a new remote (opens a browser for OAuth login)
|
|
yarn twenty remote add
|
|
|
|
# Connect to a local Twenty server (auto-detects port 2020 or 3000)
|
|
yarn twenty remote add --local
|
|
|
|
# Add a remote non-interactively (useful for CI)
|
|
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
|
|
|
|
# List all configured remotes
|
|
yarn twenty remote list
|
|
|
|
# Switch the active remote
|
|
yarn twenty remote switch <name>
|
|
```
|
|
|
|
Acreditările dvs. sunt stocate în `~/.twenty/config.json`.
|
|
|
|
## Server local de dezvoltare (`yarn twenty server`)
|
|
|
|
CLI-ul poate gestiona un server Twenty local care rulează în Docker. Acesta este același server pornit automat când creați scheletul unei aplicații cu `create-twenty-app`, dar îl puteți gestiona și manual.
|
|
|
|
### Pornirea serverului
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server start
|
|
```
|
|
|
|
Aceasta descarcă imaginea Docker `twentycrm/twenty-app-dev:latest` (dacă nu este deja prezentă), creează un container numit `twenty-app-dev` și îl pornește pe portul **2020**. CLI-ul așteaptă până când serverul trece verificarea de integritate înainte de a reveni.
|
|
|
|
Sunt create două volume Docker pentru a păstra datele între reporniri:
|
|
|
|
* `twenty-app-dev-data` — bază de date PostgreSQL
|
|
* `twenty-app-dev-storage` — stocare fișiere
|
|
|
|
Dacă portul 2020 este deja utilizat, puteți porni pe un alt port:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server start --port 3030
|
|
```
|
|
|
|
CLI-ul configurează automat `NODE_PORT` și `SERVER_URL` interne ale containerului pentru a se potrivi cu portul ales, astfel încât funcțiile logice, OAuth și toată rețeaua internă să funcționeze corect.
|
|
|
|
După pornire, serverul este înregistrat automat ca remote `local` în configurația CLI.
|
|
|
|
### Verificarea stării serverului
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server status
|
|
```
|
|
|
|
Afișează dacă serverul rulează, URL-ul său și acreditările implicite de autentificare (`tim@apple.dev` / `tim@apple.dev`).
|
|
|
|
### Vizualizarea jurnalelor serverului
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server logs
|
|
```
|
|
|
|
Transmite în flux jurnalele containerului. Folosiți `--lines` pentru a controla câte linii recente să fie afișate:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server logs --lines 100
|
|
```
|
|
|
|
### Oprirea serverului
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server stop
|
|
```
|
|
|
|
Oprește containerul. Datele dvs. sunt păstrate în volumele Docker — următoarea comandă `start` reia de unde ați rămas.
|
|
|
|
### Resetarea serverului
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server reset
|
|
```
|
|
|
|
Elimină containerul **și** șterge ambele volume Docker, ștergând toate datele. Următoarea comandă `start` creează o instanță nouă.
|
|
|
|
<Note>
|
|
Serverul necesită ca **Docker** să ruleze. Dacă vedeți eroarea "Docker not running", asigurați-vă că Docker Desktop (sau demonul Docker) este pornit.
|
|
</Note>
|
|
|
|
### Referință pentru comenzi
|
|
|
|
| Comandă | Descriere |
|
|
| -------------------------------------- | ------------------------------------------------------------- |
|
|
| `yarn twenty server start` | Pornește serverul local (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ă starea serverului, URL-ul și acreditările |
|
|
| `yarn twenty server logs` | Transmite în flux jurnalele serverului |
|
|
| `yarn twenty server logs --lines 100` | Afișează ultimele 100 de linii de jurnal |
|
|
| `yarn twenty server reset` | Șterge toate datele și pornește de la zero |
|
|
|
|
## CI cu GitHub Actions
|
|
|
|
Scaffolderul generează un workflow GitHub Actions gata de utilizare în `.github/workflows/ci.yml`. Rulează automat testele de integrare la fiecare push pe `main` și la pull request-uri.
|
|
|
|
Workflow-ul:
|
|
|
|
1. Preia codul
|
|
2. Pornește un server Twenty temporar folosind acțiunea `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
|
|
3. Instalează dependențele cu `yarn install --immutable`
|
|
4. Rulează `yarn test` cu `TWENTY_API_URL` și `TWENTY_API_KEY` injectate din rezultatele acțiunii
|
|
|
|
```yaml .github/workflows/ci.yml
|
|
name: CI
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
- main
|
|
pull_request: {}
|
|
|
|
env:
|
|
TWENTY_VERSION: latest
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
|
|
- name: Spawn Twenty instance
|
|
id: twenty
|
|
uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
|
|
with:
|
|
twenty-version: ${{ env.TWENTY_VERSION }}
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
|
|
- name: Enable Corepack
|
|
run: corepack enable
|
|
|
|
- name: Setup Node.js
|
|
uses: actions/setup-node@v4
|
|
with:
|
|
node-version-file: '.nvmrc'
|
|
cache: 'yarn'
|
|
|
|
- name: Install dependencies
|
|
run: yarn install --immutable
|
|
|
|
- name: Run integration tests
|
|
run: yarn test
|
|
env:
|
|
TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
|
|
TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
|
|
```
|
|
|
|
Nu trebuie să configurați niciun secret — acțiunea `spawn-twenty-docker-image` pornește un server Twenty efemer direct în runner și oferă detaliile de conectare. Secretul `GITHUB_TOKEN` este furnizat automat de GitHub.
|
|
|
|
Pentru a fixa o versiune Twenty specifică în loc de `latest`, modificați variabila de mediu `TWENTY_VERSION` din partea de sus a workflow-ului.
|
|
|
|
## Configurare manuală (fără generator)
|
|
|
|
Dacă preferați să configurați totul manual în loc să folosiți `create-twenty-app`, o puteți face în doi pași.
|
|
|
|
**1. Adăugați `twenty-sdk` și `twenty-client-sdk` ca dependențe:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn add twenty-sdk twenty-client-sdk
|
|
```
|
|
|
|
**2. Adăugați un script `twenty` în `package.json`:**
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Acum puteți rula `yarn twenty dev`, `yarn twenty help` și toate celelalte comenzi.
|
|
|
|
<Note>
|
|
Nu instalați `twenty-sdk` global. Folosiți-l întotdeauna ca dependență locală de proiect, astfel încât fiecare proiect să își poată fixa propria versiune.
|
|
</Note>
|
|
|
|
## Depanare
|
|
|
|
Dacă întâmpinați probleme:
|
|
|
|
* Asigurați-vă că Docker rulează înainte de a porni scaffolderul cu o instanță locală.
|
|
* Asigurați-vă că folosiți **Node.js 24+** (`node -v` pentru verificare).
|
|
* Asigurați-vă că **Corepack este activat** (`corepack enable`) astfel încât Yarn 4 să fie disponibil.
|
|
* Încercați să ștergeți `node_modules` și să rulați din nou `yarn install` dacă dependențele par deteriorate.
|
|
|
|
Încă aveți probleme? Cereți ajutor pe [Discordul Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
|