github-actions[bot]
0b8421a45a
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
256 lines
13 KiB
Plaintext
256 lines
13 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>
|
|
|
|
## Ce sunt aplicațiile?
|
|
|
|
Aplicațiile vă permit să extindeți Twenty cu obiecte personalizate, câmpuri, funcții logice, componente front-end, abilități IA și altele — toate gestionate ca cod. În loc să configurați totul prin interfața de utilizator (UI), vă definiți modelul de date și logica în TypeScript și le implementați în unul sau mai multe spații de lucru.
|
|
|
|
## 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ă.
|
|
|
|
## Create your first app
|
|
|
|
### Scaffold your app
|
|
|
|
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.
|
|
|
|
### Set up a local Twenty instance
|
|
|
|
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>
|
|
|
|
### Sign in to your workspace
|
|
|
|
Î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>
|
|
|
|
### Authorize the app
|
|
|
|
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>
|
|
|
|
### Start developing
|
|
|
|
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>
|
|
|
|
### See your app in 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.
|
|
|
|
---
|
|
|
|
## Ce puteți construi
|
|
|
|
Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
|
|
|
|
| Entity | What it does |
|
|
| ------------------------ | --------------------------------------------------------------------------------------------- |
|
|
| **Objects & Fields** | Define custom data models (like Post Card, Invoice) with typed fields |
|
|
| **Funcții logice** | Server-side TypeScript functions triggered by HTTP routes, cron schedules, or database events |
|
|
| **Componente front-end** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
|
|
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
|
|
| **Views & Navigation** | Pre-configured list views and sidebar menu items for your objects |
|
|
| **Layouturi de pagină** | Custom record detail pages with tabs and widgets |
|
|
|
|
Head over to [Building Apps](/l/ro/developers/extend/apps/building) for a detailed guide on each entity type.
|
|
|
|
---
|
|
|
|
## Structura proiectului
|
|
|
|
The scaffolder generates the following file structure:
|
|
|
|
```text filename="my-twenty-app/"
|
|
my-twenty-app/
|
|
package.json
|
|
yarn.lock
|
|
.gitignore
|
|
.nvmrc
|
|
.yarnrc.yml
|
|
.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
|
|
├── default-role.ts # Default role for logic functions
|
|
├── constants/
|
|
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
|
|
└── __tests__/
|
|
├── setup-test.ts # Test setup (server health check, config)
|
|
└── app-install.integration-test.ts # Integration test
|
|
```
|
|
|
|
### Starting from an example
|
|
|
|
To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Examples are sourced from the [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/l/ro/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
|
|
|
|
### 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/default-role.ts` | Default role that controls what your logic functions can access. |
|
|
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
|
|
| `src/__tests__/` | Teste de integrare (configurare + test exemplu). |
|
|
| `public/` | Resurse statice (imagini, fonturi) servite împreună cu aplicația. |
|
|
|
|
## Local development server
|
|
|
|
The scaffolder already started a local Twenty server for you. To manage it later, use `yarn twenty server`:
|
|
|
|
| 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 |
|
|
|
|
Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
|
|
|
|
<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>
|
|
|
|
## 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).
|