246 lines
11 KiB
Plaintext
246 lines
11 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.
|
|
|
|
**Ce puteți face astăzi:**
|
|
|
|
* Definiți obiecte și câmpuri personalizate sub formă de cod (model de date gestionat)
|
|
* Construiți funcții logice cu declanșatoare personalizate (rute HTTP, cron, evenimente ale bazei de date)
|
|
* Definiți abilități pentru agenți de IA
|
|
* Construiți componente front-end care se afișează în interfața Twenty
|
|
* Implementați aceeași aplicație în mai multe spații de lucru
|
|
|
|
## Cerințe
|
|
|
|
* Node.js 24+ și Yarn 4
|
|
* Docker (pentru serverul local de dezvoltare Twenty)
|
|
|
|
## Începeți
|
|
|
|
Creați o aplicație nouă folosind generatorul oficial, apoi autentificați-vă și începeți să dezvoltați:
|
|
|
|
```bash filename="Terminal"
|
|
# Scaffold a new app (includes all examples by default)
|
|
npx create-twenty-app@latest my-twenty-app
|
|
cd my-twenty-app
|
|
|
|
# Start dev mode: automatically syncs local changes to your workspace
|
|
yarn twenty dev
|
|
```
|
|
|
|
Generatorul de schelet acceptă două moduri pentru a controla ce fișiere de exemplu sunt incluse:
|
|
|
|
```bash filename="Terminal"
|
|
# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill, agent)
|
|
npx create-twenty-app@latest my-app
|
|
|
|
# Minimal: only core files (application-config.ts and default-role.ts)
|
|
npx create-twenty-app@latest my-app --minimal
|
|
```
|
|
|
|
De aici puteți:
|
|
|
|
```bash filename="Terminal"
|
|
# Add a new entity to your application (guided)
|
|
yarn twenty add
|
|
|
|
# Watch your application's function logs
|
|
yarn twenty function:logs
|
|
|
|
# Execute a function by name
|
|
yarn twenty function:execute -n my-function -p '{"name": "test"}'
|
|
|
|
# Execute the pre-install function
|
|
yarn twenty function:execute --preInstall
|
|
|
|
# Execute the post-install function
|
|
yarn twenty function:execute --postInstall
|
|
|
|
# Uninstall the application from the current workspace
|
|
yarn twenty uninstall
|
|
|
|
# Display commands' help
|
|
yarn twenty help
|
|
```
|
|
|
|
Consultați și: paginile de referință CLI pentru [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) și [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
|
|
|
|
## Structura proiectului (generată)
|
|
|
|
Când rulați `npx create-twenty-app@latest my-twenty-app`, generatorul:
|
|
|
|
* Copiază o aplicație de bază minimală în `my-twenty-app/`
|
|
* Adaugă o dependență locală `twenty-sdk` și configurația Yarn 4
|
|
* Creează fișiere de configurare și scripturi conectate la CLI-ul `twenty`
|
|
* Generează fișierele de bază (configurația aplicației, rolul implicit al funcțiilor, funcțiile de pre-instalare și post-instalare) plus fișiere de exemplu în funcție de modul de generare a scheletului.
|
|
|
|
O aplicație proaspăt generată cu modul implicit `--exhaustive` arată astfel:
|
|
|
|
```text filename="my-twenty-app/"
|
|
my-twenty-app/
|
|
package.json
|
|
yarn.lock
|
|
.gitignore
|
|
.nvmrc
|
|
.yarnrc.yml
|
|
.yarn/
|
|
install-state.gz
|
|
.oxlintrc.json
|
|
tsconfig.json
|
|
README.md
|
|
public/ # Public assets folder (images, fonts, etc.)
|
|
src/
|
|
├── application-config.ts # Required - main application configuration
|
|
├── 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
|
|
│ ├── pre-install.ts # Pre-install logic function
|
|
│ └── post-install.ts # Post-install logic function
|
|
├── front-components/
|
|
│ └── hello-world.tsx # Example 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
|
|
```
|
|
|
|
Cu `--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`).
|
|
|
|
Pe scurt:
|
|
|
|
* **package.json**: Declară numele aplicației, versiunea, motoarele (Node 24+, Yarn 4) și adaugă `twenty-sdk` plus un script `twenty` care deleagă către CLI-ul local `twenty`. Rulați `yarn twenty help` pentru a lista toate comenzile disponibile.
|
|
* **.gitignore**: Ignoră artefacte comune precum `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, foldere de coverage, fișiere jurnal și fișiere `.env*`.
|
|
* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Blochează și configurează lanțul de instrumente Yarn 4 folosit de proiect.
|
|
* **.nvmrc**: Fixează versiunea Node.js așteptată de proiect.
|
|
* **.oxlintrc.json** și **tsconfig.json**: Oferă linting și configurație TypeScript pentru fișierele TypeScript ale aplicației.
|
|
* **README.md**: Un README scurt în rădăcina aplicației, cu instrucțiuni de bază.
|
|
* **public/**: Un folder pentru stocarea resurselor publice (imagini, fonturi, fișiere statice) care vor fi servite împreună cu aplicația dvs. Fișierele plasate aici sunt încărcate în timpul sincronizării și sunt accesibile la rulare.
|
|
* **src/**: Locul principal unde vă definiți aplicația sub formă de cod
|
|
|
|
### Detectarea entităților
|
|
|
|
SDK-ul detectează entitățile analizând fișierele TypeScript pentru apeluri **`export default define<Entity>({...})`**. Fiecare tip de entitate are o funcție ajutătoare corespunzătoare, exportată din `twenty-sdk`:
|
|
|
|
| Funcție ajutătoare | Tipul entității |
|
|
| -------------------------------- | -------------------------------------------------------------- |
|
|
| `defineObject` | Definiții de obiecte personalizate |
|
|
| `defineLogicFunction` | Definiții de funcții de logică |
|
|
| `definePreInstallLogicFunction` | Funcție logică de pre-instalare (rulează înainte de instalare) |
|
|
| `definePostInstallLogicFunction` | Funcție logică post-instalare (rulează după instalare) |
|
|
| `defineFrontComponent` | Definiții ale componentelor de interfață |
|
|
| `defineRole` | Definiții de rol |
|
|
| `defineField` | Extensii de câmp pentru obiectele existente |
|
|
| `defineView` | Definiții pentru vizualizări salvate |
|
|
| `defineNavigationMenuItem` | Definiții pentru elemente de meniu de navigare |
|
|
| `defineSkill` | Definiții ale abilităților agentului IA |
|
|
|
|
<Note>
|
|
**Denumirea fișierelor este flexibilă.** Detectarea entităților se bazează pe AST — SDK-ul scanează fișierele sursă pentru tiparul `export default define<Entity>({...})`. Puteți organiza fișierele și folderele cum doriți. Gruparea după tipul de entitate (de exemplu, `logic-functions/`, `roles/`) este doar o convenție pentru organizarea codului, nu o cerință.
|
|
</Note>
|
|
|
|
Exemplu de entitate detectată:
|
|
|
|
```typescript
|
|
// This file can be named anything and placed anywhere in src/
|
|
import { defineObject, FieldType } from 'twenty-sdk';
|
|
|
|
export default defineObject({
|
|
universalIdentifier: '...',
|
|
nameSingular: 'postCard',
|
|
// ... rest of config
|
|
});
|
|
```
|
|
|
|
Comenzile ulterioare vor adăuga mai multe fișiere și foldere:
|
|
|
|
* `yarn twenty dev` va genera automat `CoreApiClient` tipizat (pentru datele spațiului de lucru prin `/graphql`) în `node_modules/twenty-client-sdk/`. `MetadataApiClient` (pentru configurarea spațiului de lucru și încărcarea fișierelor prin `/metadata`) este livrat preconstruit și este disponibil imediat. Importați-le din `twenty-client-sdk/core` și `twenty-client-sdk/metadata`, respectiv.
|
|
* `yarn twenty add` va adăuga fișiere de definire a entităților în `src/` pentru obiectele personalizate, funcțiile, componentele front-end, rolurile, abilitățile și altele.
|
|
|
|
## Autentificare
|
|
|
|
Prima dată când rulați `yarn twenty auth:login`, vi se vor solicita:
|
|
|
|
* URL-ul API (implicit http://localhost:3000 sau profilul spațiului de lucru curent)
|
|
* Cheie API
|
|
|
|
Acreditările dvs. sunt stocate per utilizator în `~/.twenty/config.json`. Puteți menține mai multe profiluri și comuta între ele.
|
|
|
|
### Gestionarea spațiilor de lucru
|
|
|
|
```bash filename="Terminal"
|
|
# Login interactively (recommended)
|
|
yarn twenty auth:login
|
|
|
|
# Login to a specific workspace profile
|
|
yarn twenty auth:login --workspace my-custom-workspace
|
|
|
|
# List all configured workspaces
|
|
yarn twenty auth:list
|
|
|
|
# Switch the default workspace (interactive)
|
|
yarn twenty auth:switch
|
|
|
|
# Switch to a specific workspace
|
|
yarn twenty auth:switch production
|
|
|
|
# Check current authentication status
|
|
yarn twenty auth:status
|
|
```
|
|
|
|
După ce ați schimbat spațiul de lucru cu `yarn twenty auth:switch`, toate comenzile ulterioare vor folosi implicit acel spațiu de lucru. Îl puteți totuși suprascrie temporar cu `--workspace <name>`.
|
|
|
|
## Configurare manuală (fără generator)
|
|
|
|
Deși recomandăm utilizarea `create-twenty-app` pentru cea mai bună experiență de început, puteți configura și un proiect manual. Nu instalați CLI-ul global. În schimb, adăugați `twenty-sdk` ca dependență locală și conectați un singur script în package.json-ul dvs.:
|
|
|
|
```bash filename="Terminal"
|
|
yarn add -D twenty-sdk
|
|
```
|
|
|
|
Apoi adăugați un script `twenty`:
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Acum poți rula toate comenzile prin `yarn twenty <command>`, de ex. `yarn twenty dev`, `yarn twenty help`, etc.
|
|
|
|
## Cum să folosești o instanță Twenty locală
|
|
|
|
Dacă rulezi deja local o instanță Twenty (de exemplu prin `npx nx start twenty-server`), te poți conecta la ea în loc să folosești Docker:
|
|
|
|
```bash filename="Terminal"
|
|
# During scaffolding — skip Docker, connect to your running instance
|
|
npx create-twenty-app@latest my-app --port 3000
|
|
|
|
# Or after scaffolding — add a remote pointing to your instance
|
|
yarn twenty remote add --local --port 3000
|
|
```
|
|
|
|
## Depanare
|
|
|
|
* Erori de autentificare: rulați `yarn twenty auth:login` și asigurați-vă că cheia API are permisiunile necesare.
|
|
* Nu se poate conecta la server: verificați URL-ul API și că serverul Twenty este accesibil.
|
|
* Tipuri sau client lipsă/învechite: repornește `yarn twenty dev` — acesta generează automat clientul tipizat.
|
|
* Modul dev nu sincronizează: asigură-te că `yarn twenty dev` rulează și că modificările nu sunt ignorate de mediul tău.
|
|
|
|
Canal de ajutor pe Discord: https://discord.com/channels/1130383047699738754/1130386664812982322
|