---
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).
