github-actions[bot]
ebee7d71b9
Created by Github action <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22715?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: github-actions <github-actions@twenty.com>
167 lines
11 KiB
Plaintext
167 lines
11 KiB
Plaintext
---
|
|
title: Avvio rapido
|
|
icon: rocket
|
|
description: Crea la tua prima app Twenty in pochi minuti.
|
|
---
|
|
|
|
## Prerequisiti
|
|
|
|
* **Node.js 24.5+** — [Scarica](https://nodejs.org/)
|
|
* **Yarn 4** — incluso con Node.js tramite Corepack. Abilitalo: `corepack enable`
|
|
* **Docker** — [Scarica](https://www.docker.com/products/docker-desktop/). Necessario per eseguire un server Twenty locale. Salta se hai già Twenty in esecuzione altrove.
|
|
|
|
La creazione di un'app Twenty ha tre fasi. Lo strumento di scaffolding le combina in un unico comando per il percorso ottimale, ma ogni fase è un concetto distinto — quando qualcosa fallisce, sapere in quale fase ti trovi indica cosa correggere.
|
|
|
|
| Fase | Cosa fai | Strumento | Risultato |
|
|
| ----------------------- | ------------------------------------------------------ | ----------------------------------- | ---------------------------------- |
|
|
| **1. Crea struttura** | Genera il codice sorgente dell'app | `npx create-twenty-app` | Un progetto TypeScript sul disco |
|
|
| **2. Esegui un server** | Avvia un server Twenty con cui sincronizzare | Docker + `yarn twenty docker:start` | Un'istanza Twenty in esecuzione |
|
|
| **3. Sincronizza** | Sincronizza in tempo reale il tuo codice con il server | `yarn twenty dev` | Le tue modifiche compaiono nell'UI |
|
|
|
|
---
|
|
|
|
## Fase 1 — Crea la struttura del progetto
|
|
|
|
Crea una nuova app dal modello:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Lo scaffolder è non interattivo: il nome della directory diventa il nome dell'app. Passa `--display-name` e `--description` per personalizzare i metadati generati (puoi anche modificarli in seguito in `src/constants/universal-identifiers.ts`). Questo genera un progetto TypeScript in `my-twenty-app/` con un `application-config.ts` iniziale, un ruolo predefinito, workflow CI/CD e un test di integrazione.
|
|
|
|
**Dopo questa fase:** hai il codice sorgente dell'app sulla tua macchina. Non è ancora in esecuzione — questa è la Fase 2.
|
|
|
|
---
|
|
|
|
## Fase 2 — Esegui un server Twenty locale
|
|
|
|
La tua app ha bisogno di un server Twenty con cui sincronizzarsi. Il server è un'istanza Twenty completa — UI, API GraphQL, PostgreSQL — in esecuzione in locale su Docker. Il tuo codice locale carica le sue definizioni su quel server, che le rende visibili nell'UI.
|
|
|
|
Lo scaffolder avvia un'istanza per te: con Docker in esecuzione, scarica l'immagine `twentycrm/twenty-app-dev`, la avvia sulla porta `2020` e autentica la CLI sullo spazio di lavoro demo prepopolato (`tim@apple.dev`) — non è necessario effettuare l'accesso.
|
|
|
|
Per connetterti invece a un server Twenty esistente, passa `--url \<your-server-url>`. I server remoti eseguono l'autenticazione con OAuth: si apre un browser così puoi effettuare l'accesso e fare clic su **Authorize**, concedendo alla CLI l'accesso al tuo spazio di lavoro. (Puoi anche scegliere di utilizzare OAuth in locale con `--authentication-method oauth` — accedi con `tim@apple.dev` / `tim@apple.dev`.)
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Schermata di accesso di Twenty" />
|
|
</div>
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Schermata di autorizzazione della CLI di Twenty" />
|
|
</div>
|
|
|
|
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>
|
|
|
|
**Dopo questa fase:** hai un server Twenty in esecuzione su [http://localhost:2020](http://localhost:2020) con la tua CLI autorizzata a sincronizzarsi con esso.
|
|
|
|
<Note>
|
|
Se Docker non è installato o in esecuzione, lo strumento di scaffolding ti indicherà il comando di avvio corretto per il tuo sistema operativo. Quando Docker è attivo, puoi riprendere con `yarn twenty docker:start` — non è necessario rifare lo scaffolding.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Fase 3 — Sincronizza le tue modifiche
|
|
|
|
Questo è il ciclo interno in cui passerai la maggior parte del tempo.
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
Questo osserva `src/`, ricompila a ogni modifica e sincronizza il risultato con il server. Modifica un file, salvalo e in pochi secondi il server riflette la modifica. Vedrai un pannello di stato in tempo reale nel terminale.
|
|
|
|
Per un output più dettagliato (log di build, richieste di sincronizzazione, tracce di errore), aggiungi `--verbose`.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.png" alt="Output del terminale in modalità sviluppo" />
|
|
</div>
|
|
|
|
Apri [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Dovresti vedere la tua app sotto **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 vedere la sua **registrazione dell'applicazione** — un record a livello di server che descrive la tua app (nome, identificatore, credenziali OAuth, origine). 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'installazione nello spazio di lavoro. La scheda **About** mostra la versione e le opzioni di gestione.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="App installata" />
|
|
</div>
|
|
|
|
**Dopo questa fase:** hai un ciclo di sviluppo in tempo reale. Modifica qualsiasi file in `src/` e compare nell'UI.
|
|
|
|
### Sincronizzazione una tantum per CI e script
|
|
|
|
Usa `plan` e `apply` per eseguire la stessa pipeline una volta, senza watcher:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty plan # preview the metadata changes without applying them
|
|
yarn twenty apply # show the plan, then apply it
|
|
```
|
|
|
|
| Comando | Comportamento | Quando usarlo |
|
|
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
| `yarn twenty dev` | Monitora e risincronizza a ogni modifica. Rimane in esecuzione finché non lo interrompi. | Sviluppo locale interattivo. |
|
|
| `yarn twenty apply` | Singola build + sincronizzazione, termina con codice `0` in caso di successo, `1` in caso di errore. Richiede conferma per le modifiche distruttive (passa `--force` per saltarla). | CI, hook pre-commit, agenti IA, flussi di lavoro scriptati. |
|
|
| `yarn twenty plan` | Crea e stampa le modifiche ai metadati **senza applicarle**. | Ispezionare quali modifiche verrebbero apportate da una sincronizzazione prima di confermarla. |
|
|
|
|
Tutte le modalità richiedono un remoto autenticato. Vedi [Sincronizzazione e ripristino](/l/it/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) per maggiori informazioni su `plan`.
|
|
|
|
<Note>
|
|
`yarn twenty dev --once` e `yarn twenty dev --once --dry-run` sono alias deprecati di `yarn twenty apply` e `yarn twenty plan`.
|
|
</Note>
|
|
|
|
### Opzioni della modalità di sviluppo
|
|
|
|
| Opzione | Descrizione |
|
|
| ------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
| `--force` | Applica modifiche distruttive (eliminazioni) senza conferma. |
|
|
| `--debounceMs \<ms>` | Imposta il ritardo di debounce delle modifiche ai file in millisecondi (predefinito: `1000`). |
|
|
| `--verbose` / `--debug` | Mostra log di build dettagliati, richieste di sincronizzazione e tracce di errore. |
|
|
|
|
## 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** | Modelli di dati personalizzati (Cartolina, Fattura, ecc.) con campi tipizzati |
|
|
| **Funzioni logiche** | TypeScript lato server attivato 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 |
|
|
| **Layout di pagina** | Pagine di dettaglio dei record personalizzate con schede e widget |
|
|
|
|
Riferimento completo: [Concetti](/l/it/developers/extend/apps/getting-started/concepts).
|
|
|
|
## Prossimi passaggi
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Configurazione" icon="screwdriver-wrench" href="/l/it/developers/extend/apps/config/overview">
|
|
Identità dell'applicazione, ruolo predefinito, hook di installazione, asset pubblici.
|
|
</Card>
|
|
<Card title="Dati" icon="database" href="/l/it/developers/extend/apps/data/overview">
|
|
Oggetti, campi e relazioni bidirezionali.
|
|
</Card>
|
|
<Card title="Logica" icon="bolt" href="/l/it/developers/extend/apps/logic/overview">
|
|
Funzioni logiche, skill, agenti e connessioni OAuth.
|
|
</Card>
|
|
<Card title="Layout" icon="table-columns" href="/l/it/developers/extend/apps/layout/overview">
|
|
Viste, navigazione, layout di pagina, componenti front-end.
|
|
</Card>
|
|
<Card title="Operazioni" icon="rocket" href="/l/it/developers/extend/apps/operations/overview">
|
|
CLI, test, remoti, CI e pubblicazione della tua app.
|
|
</Card>
|
|
</CardGroup>
|