271 lines
15 KiB
Plaintext
271 lines
15 KiB
Plaintext
---
|
|
title: Per iniziare
|
|
description: Crea la tua prima app Twenty in pochi minuti.
|
|
---
|
|
|
|
<Warning>
|
|
Le app sono attualmente in fase alfa. La funzionalità funziona ma è ancora in evoluzione.
|
|
</Warning>
|
|
|
|
## Cosa sono le app?
|
|
|
|
Le app ti consentono di estendere Twenty con oggetti, campi, funzioni logiche, componenti front-end, competenze IA e altro ancora — il tutto gestito come codice. Invece di configurare tutto tramite l'interfaccia utente, definisci in TypeScript il modello dati e la logica e li distribuisci in uno o più spazi di lavoro.
|
|
|
|
## Prerequisiti
|
|
|
|
Prima di iniziare, assicurati che quanto segue sia installato sul tuo computer:
|
|
|
|
* **Node.js 24+** — [Scarica qui](https://nodejs.org/)
|
|
* **Yarn 4** — Incluso con Node.js tramite Corepack. Abilitalo eseguendo `corepack enable`
|
|
* **Docker** — [Scarica qui](https://www.docker.com/products/docker-desktop/). Necessario per eseguire un'istanza locale di Twenty. Non necessario se hai già un server Twenty in esecuzione.
|
|
|
|
## Crea la tua prima app
|
|
|
|
### Crea lo scheletro della tua app
|
|
|
|
Apri un terminale ed esegui:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Ti verrà chiesto di inserire un nome e una descrizione per la tua app. Premi **Invio** per accettare i valori predefiniti.
|
|
|
|
Questo crea una nuova cartella chiamata `my-twenty-app` con tutto il necessario.
|
|
|
|
### Configura un'istanza locale di Twenty
|
|
|
|
Lo strumento di scaffolding chiederà:
|
|
|
|
> **Vuoi configurare un'istanza locale di Twenty?**
|
|
|
|
* **Digita `yes`** (consigliato) — Questo scarica l'immagine Docker `twenty-app-dev` e avvia un server Twenty locale sulla porta `2020`. Assicurati che Docker sia in esecuzione prima di continuare.
|
|
* **Digita `no`** — Sceglilo se hai già un server Twenty in esecuzione in locale.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Avviare l'istanza locale?" />
|
|
</div>
|
|
|
|
### Accedi al tuo spazio di lavoro
|
|
|
|
Successivamente si aprirà una finestra del browser con la pagina di accesso di Twenty. Accedi con l'account demo preconfigurato:
|
|
|
|
* **Email:** `tim@apple.dev`
|
|
* **Password:** `tim@apple.dev`
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Schermata di accesso di Twenty" />
|
|
</div>
|
|
|
|
### Autorizza l'app
|
|
|
|
Dopo l'accesso, vedrai una schermata di autorizzazione. Questo consente alla tua app di interagire con il tuo spazio di lavoro.
|
|
|
|
Fai clic su **Authorize** per continuare.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Schermata di autorizzazione della CLI di Twenty" />
|
|
</div>
|
|
|
|
Una volta autorizzato, il terminale confermerà che tutto è configurato.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App creata con successo" />
|
|
</div>
|
|
|
|
### Inizia a sviluppare
|
|
|
|
Entra nella nuova cartella della tua app e avvia il server di sviluppo:
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
Questo controlla i file sorgente, ricompila a ogni modifica e sincronizza automaticamente la tua app con il server Twenty locale. Dovresti vedere un pannello di stato in tempo reale nel terminale.
|
|
|
|
Per un output più dettagliato (log di build, richieste di sincronizzazione, tracce di errore), usa il flag `--verbose`:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --verbose
|
|
```
|
|
|
|
<Warning>
|
|
La modalità di sviluppo è disponibile solo sulle istanze di Twenty in esecuzione in modalità sviluppo (`NODE_ENV=development`). Le istanze di produzione rifiutano le richieste di sincronizzazione in modalità sviluppo. Usa `yarn twenty deploy` per distribuire sui server di produzione — vedi [Pubblicazione delle app](/l/it/developers/extend/apps/publishing) per i dettagli.
|
|
</Warning>
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Output del terminale in modalità sviluppo" />
|
|
</div>
|
|
|
|
#### Sincronizzazione una tantum con `yarn twenty dev --once`
|
|
|
|
Se non vuoi un watcher in esecuzione in background (ad esempio in una pipeline CI, un hook di Git o un flusso di lavoro scriptato), passa il flag `--once`. Esegue la stessa pipeline di `yarn twenty dev` — genera il manifest, effettua il bundling dei file, carica, sincronizza, rigenera il client API tipizzato — ma **termina non appena la sincronizzazione è completata**:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --once
|
|
```
|
|
|
|
| Comando | Comportamento | Quando usarlo |
|
|
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
| `yarn twenty dev` | Monitora i file sorgente e risincronizza a ogni modifica. Rimane in esecuzione finché non lo interrompi. | Sviluppo locale interattivo — vuoi il pannello di stato in tempo reale e un ciclo di feedback immediato. |
|
|
| `yarn twenty dev --once` | Esegue una singola build + sincronizzazione, quindi termina con codice `0` in caso di successo o `1` in caso di errore. | Script, CI, hook pre-commit, agenti IA e qualsiasi flusso di lavoro non interattivo. |
|
|
|
|
Entrambe le modalità richiedono un server Twenty in esecuzione in modalità di sviluppo e un remote autenticato — si applicano gli stessi prerequisiti.
|
|
|
|
### Visualizza la tua app in Twenty
|
|
|
|
Apri [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) nel browser. Vai su **Settings > Apps** e seleziona la scheda **Developer**. Dovresti vedere la tua app elencata in **Your Apps**:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Elenco Your Apps che mostra My twenty app" />
|
|
</div>
|
|
|
|
Fai clic su **My twenty app** per aprire la sua **registrazione dell'applicazione**. Una registrazione è un record a livello di server che descrive la tua app — il suo nome, identificatore univoco, credenziali OAuth e origine (locale, npm o tarball). Risiede sul server, non all'interno di uno spazio di lavoro specifico. Quando installi un'app in uno spazio di lavoro, Twenty crea un'**applicazione** con ambito dello spazio di lavoro che rimanda a questa registrazione. Una registrazione può essere installata in più spazi di lavoro sullo stesso server.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Dettagli della registrazione dell'applicazione" />
|
|
</div>
|
|
|
|
Fai clic su **View installed app** per vedere l'app installata. La scheda **About** mostra la versione corrente e le opzioni di gestione:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="App installata — scheda About" />
|
|
</div>
|
|
|
|
Passa alla scheda **Content** per vedere tutto ciò che la tua app fornisce — oggetti, campi, funzioni logiche e agenti:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="App installata — scheda Content" />
|
|
</div>
|
|
|
|
È tutto pronto! Modifica qualsiasi file in `src/` e le modifiche verranno rilevate automaticamente.
|
|
|
|
---
|
|
|
|
## Cosa puoi creare
|
|
|
|
Le app sono composte da **entità** — ciascuna definita come un file TypeScript con un singolo `export default`:
|
|
|
|
| Entità | Cosa fa |
|
|
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
|
| **Oggetti e campi** | Definisci modelli di dati personalizzati (come Post Card, Invoice) con campi tipizzati |
|
|
| **Funzioni logiche** | Funzioni TypeScript lato server attivate da route HTTP, pianificazioni cron o eventi del database |
|
|
| **Componenti front-end** | Componenti React che vengono renderizzati all'interno dell'UI di Twenty (pannello laterale, widget, menu comandi) |
|
|
| **Skill e agenti** | Funzionalità di IA — istruzioni riutilizzabili e assistenti autonomi |
|
|
| **Viste e navigazione** | Viste elenco preconfigurate e voci di menu della barra laterale per i tuoi oggetti |
|
|
| **Layout di pagina** | Pagine di dettaglio dei record personalizzate con schede e widget |
|
|
|
|
Vai a [Creare app](/l/it/developers/extend/apps/building) per una guida dettagliata su ogni tipo di entità.
|
|
|
|
---
|
|
|
|
## Struttura del progetto
|
|
|
|
Lo scaffolder genera la seguente struttura dei file:
|
|
|
|
```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
|
|
```
|
|
|
|
### Partire da un esempio
|
|
|
|
Per iniziare da un esempio più completo con oggetti personalizzati, campi, funzioni logiche, componenti front-end e altro, usa il flag `--example`:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Gli esempi provengono dalla directory [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) su GitHub. Puoi anche aggiungere singole entità a un progetto esistente con `yarn twenty add` (vedi [Creare app](/l/it/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
|
|
|
|
### File principali
|
|
|
|
| File / Cartella | Scopo |
|
|
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `package.json` | Dichiara il nome, la versione e le dipendenze della tua app. Include uno script `twenty` così puoi eseguire `yarn twenty help` per vedere tutti i comandi. |
|
|
| `src/application-config.ts` | **Obbligatorio.** Il file di configurazione principale della tua app. |
|
|
| `src/default-role.ts` | Ruolo predefinito che controlla a cosa possono accedere le tue funzioni logiche. |
|
|
| `src/constants/universal-identifiers.ts` | UUID generati automaticamente e metadati dell'app (nome visualizzato, descrizione). |
|
|
| `src/__tests__/` | Test di integrazione (setup + test di esempio). |
|
|
| `public/` | Asset statici (immagini, font) serviti insieme alla tua app. |
|
|
|
|
## Server di sviluppo locale
|
|
|
|
Lo scaffolder ha già avviato per te un server Twenty locale. Per gestirlo in seguito, usa `yarn twenty server`:
|
|
|
|
| Comando | Descrizione |
|
|
| -------------------------------------- | --------------------------------------------------------- |
|
|
| `yarn twenty server start` | Avvia il server locale (scarica l'immagine se necessario) |
|
|
| `yarn twenty server start --port 3030` | Avvia su una porta personalizzata |
|
|
| `yarn twenty server stop` | Arresta il server (conserva i dati) |
|
|
| `yarn twenty server status` | Mostra stato del server, URL e credenziali |
|
|
| `yarn twenty server logs` | Trasmetti in streaming i log del server |
|
|
| `yarn twenty server logs --lines 100` | Mostra le ultime 100 righe di log |
|
|
| `yarn twenty server reset` | Elimina tutti i dati e riparti da zero |
|
|
|
|
I dati vengono mantenuti tra i riavvii in due volumi Docker (`twenty-app-dev-data` per PostgreSQL, `twenty-app-dev-storage` per i file). Usa `reset` per cancellare tutto e ripartire da zero.
|
|
|
|
<Note>
|
|
Il server richiede che **Docker** sia in esecuzione. Se vedi l'errore "Docker not running", assicurati che Docker Desktop (o il demone Docker) sia avviato.
|
|
</Note>
|
|
|
|
## Configurazione manuale (senza lo scaffolder)
|
|
|
|
Se preferisci configurare tutto manualmente invece di usare `create-twenty-app`, puoi farlo in due passaggi.
|
|
|
|
**1. Aggiungi `twenty-sdk` e `twenty-client-sdk` come dipendenze:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn add twenty-sdk twenty-client-sdk
|
|
```
|
|
|
|
**2. Aggiungi uno script `twenty` al tuo `package.json`:**
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Ora puoi eseguire `yarn twenty dev`, `yarn twenty help` e tutti gli altri comandi.
|
|
|
|
<Note>
|
|
Non installare `twenty-sdk` globalmente. Usalo sempre come dipendenza locale del progetto, in modo che ogni progetto possa fissare la propria versione.
|
|
</Note>
|
|
|
|
## Risoluzione dei problemi
|
|
|
|
Se riscontri problemi:
|
|
|
|
* Assicurati che **Docker sia in esecuzione** prima di avviare lo strumento di scaffolding con un'istanza locale.
|
|
* Assicurati di usare **Node.js 24+** (`node -v` per verificare).
|
|
* Assicurati che **Corepack sia abilitato** (`corepack enable`) in modo che Yarn 4 sia disponibile.
|
|
* Prova a eliminare `node_modules` ed eseguire di nuovo `yarn install` se le dipendenze sembrano danneggiate.
|
|
|
|
Ancora bloccato? Chiedi aiuto su [Discord di Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
|