> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Crearne una

Una Mini App si costruisce parlandone. Descrivi cosa deve fare, guardi l'anteprima
che compare a destra, chiedi le correzioni che servono. Il codice esiste, ed è un
piccolo progetto con i suoi file, ma lo apri solo se vuoi.

## Costruire la prima

#### Apri Mini App

È una voce della barra laterale. Trovi l'elenco delle Mini App che puoi
vedere e, in alto a destra, **Nuova Mini App**.

![La pagina Mini App con il pulsante Nuova Mini App evidenziato in alto a destra, sopra l'elenco delle Mini App esistenti](/_fern-img/5fe272ef15b6444da4221b05b4d5eb25dd927c2f64e156a7e3bc76ede9e80a95.webp)

#### Premi Nuova Mini App

Si apre il costruttore: chat a sinistra, anteprima a destra. Finché non
scrivi niente, la Mini App non esiste ancora.

![Il costruttore di una Mini App nuova: a sinistra il campo in cui descriverla con gli esempi da cui partire, a destra l'anteprima ancora vuota](/_fern-img/e8be29a7fb5548560260af7df8e3bb45ce29afc22dbb67855207b704c9f963f0.webp)

#### Descrivi cosa deve fare

Scrivi nel campo in basso a sinistra. Non serve un linguaggio tecnico: serve
dire quali dati entrano, cosa succede e cosa esce. Accanto al campo puoi
scegliere il modello che lavora.

Se non sai da dove partire, il costruttore propone alcuni esempi da cui
copiare la forma, come un calcolatore di rata o un contatore di parole.

![Il campo del costruttore con la descrizione scritta: i campi, la regola di sconto e cosa mostrare, e sotto il modello scelto e il pulsante di invio](/_fern-img/8dd8c7ce4efc8971e983c211e2d0a79c610ccde0a43a9e0e45f567580a6caf4d.webp)

#### Guarda l'AI lavorare

Sotto la risposta vedi i passaggi: **Pianifico**, in cui l'AI dice cosa sta
per fare, **Genero il codice**, in cui lo scrive, e quando serve **Verifico
il codice** e **Correggo un problema**. Un riquadro elenca le singole azioni
sui file, come «Scrivo src/App.tsx» o «Verifico RUN».

![Il riepilogo dei passaggi aperto sotto la risposta del costruttore, con quello che l'AI ha fatto in ciascuno](/_fern-img/9278a786afac2d2ebc3036835833fbe5568ae9f3380155d534fd7fd704fe227c.webp)

Ogni volta che l'AI scrive il codice, Userbot lo esegue e lo controlla prima
di mostrarlo; se non passa il controllo, l'AI lo corregge da sé. Il dettaglio
sta in [Com'è fatta una Mini App](/anatomia-miniapp).

#### Provala davvero

Al termine l'anteprima a destra è già interattiva. Inserisci un caso che
conosci, uno di cui sai già la risposta giusta. Il controllo automatico
garantisce che la Mini App funzioni, non che il risultato sia quello previsto
dal tuo listino: quello lo puoi dire solo tu.

![Il costruttore di una Mini App già generata: a destra l'anteprima funzionante con i suoi campi e il risultato, sopra le schede Codice e Anteprima, e in alto a destra Pubblica con il numero di modifiche ancora da pubblicare](/_fern-img/f06fe1670b1f7c6f90939fd2baed52e1f2a56bea1c610d46053840d7734cde14.webp)

#### Chiedi le modifiche

Torna nella chat a sinistra e scrivi cosa cambiare: *«aggiungi un campo per la
categoria»*, *«arrotonda a due decimali»*, *«il totale deve comparire in
grande sotto il pulsante»*. Ogni richiesta riprende i file dov'erano.

#### Pubblicala

Quello che hai costruito finora è una bozza: nessun collega e nessun agente
la usa finché non premi **Pubblica**, in alto a destra. Come si fa, con
l'animazione dei passaggi, sta in
[Pubblicare una Mini App](/pubblicare-miniapp).

La generazione continua anche se chiudi la scheda del browser: nell'elenco la
Mini App resta segnata **In generazione…** finché non ha finito. Per fermarla
usa il pulsante di stop, che durante la generazione prende il posto di quello di
invio.

## Scrivere una descrizione che funziona

La differenza fra una Mini App corretta al primo colpo e cinque giri di correzioni
sta quasi sempre nella prima frase. Una descrizione utile dice tre cose: **quali
campi**, **quale regola**, **quale risultato**.

| Invece di                   | Scrivi                                                                                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| «Un calcolatore di sconti»  | «Campi: quantità, categoria prodotto, prezzo di listino. Sconto del 5% sopra 50 pezzi, del 10% sopra 200. Mostra prezzo scontato e risparmio.»          |
| «Un modulo per i clienti»   | «Campi obbligatori: ragione sociale, partita IVA, email, referente. Facoltativi: telefono, note. In fondo un pulsante che restituisce i dati raccolti.» |
| «Un convertitore di valute» | «Campo importo in euro, campo valuta di destinazione con le tre valute che usiamo, cambio fisso indicato da me. Mostra l'importo convertito.»           |

Se una regola ha eccezioni, dichiarale nella descrizione. Quello che non scrivi
viene deciso al posto tuo.

Se la Mini App deve leggere dati da un servizio web o ricordare qualcosa fra un
uso e l'altro, dillo: l'AI aggiunge una funzione server.
→ [Funzioni server e dati](/miniapp-server)

## L'anteprima e il codice

Sopra il pannello di destra ci sono due schede:

* **Anteprima**: la Mini App funzionante, nella sua versione di bozza. Mentre si
  prepara compare «Compilo l'anteprima…»
* **Codice**: i file del progetto, con l'albero a sinistra. Il file principale
  ha l'etichetta **entry**

Non devi toccare il codice per lavorare. Ti serve quando vuoi una modifica minima
e chirurgica, come cambiare un'etichetta o correggere una soglia, invece di
chiederla in chat. **Nuovo file** aggiunge un file, il menu accanto a ogni file
lo elimina, **Copia** porta negli appunti il file aperto.

![La scheda Codice: a sinistra i file del progetto, a destra il contenuto del file aperto, e in alto Copia accanto alle altre azioni del costruttore](/_fern-img/482275ecb05b5217ca26cd7c66afbc174f729e90f259289642fcd8a9e344e03e.webp)

> **Info**
>
> Il codice **si salva quando esci dal campo**: clicca fuori, apri un altro file
> o passa ad **Anteprima**, e la modifica è registrata. Non c'è un pulsante di
> salvataggio. Una modifica a mano aggiorna solo la bozza, come quelle dell'AI.

## Quando l'anteprima segnala un errore

Se la Mini App va in errore mentre la provi, sotto l'anteprima compare il
pannello **Problemi** con l'elenco degli errori. **Correggi con l'AI** passa
quegli errori al costruttore, che prova a sistemarli.

I tentativi sono al massimo tre di fila. Dopo, il pulsante si spegne e compare
«Limite di riparazioni raggiunto. Ripristina un checkpoint o modifica il
codice.» Se la riparazione non converge, Userbot riporta da solo la bozza
all'ultimo punto di ripristino salvato prima delle modifiche dell'AI.

Se invece l'anteprima non si costruisce proprio, compare «Impossibile compilare
l'anteprima. Controlla i file del progetto o riprova.»: di solito basta chiedere
in chat di sistemare l'errore, descrivendo cosa vedi.

## Nome, descrizione e parametri

Nome e descrizione si cambiano dal menu **⋯** in alto, voce **Modifica**: si apre
la finestra **Modifica Mini App**. Vale la pena curarli. Il nome è quello che
scrivi dopo la **@** in chat; la descrizione è ciò su cui l'AI decide se la Mini
App è pertinente a una richiesta.

Dallo stesso menu, **Parametri** apre lo schema dei dati: **JSON input** e
**JSON output**, cioè i campi che entrano nella Mini App e quelli che escono,
nella forma in cui li legge l'AI. Il pannello è **in sola lettura**: lo schema lo
dichiara l'AI insieme al codice.

Alla prima generazione l'AI sceglie nome, descrizione e schema. Dalle richieste
successive non li tocca più, a meno che tu non lo chieda in modo esplicito:
*«il campo categoria deve essere una scelta fra Standard, Premium e Outlet»*,
*«la quantità è obbligatoria»*, *«restituisci anche il risparmio in euro»*. L'AI
riscrive codice e schema insieme, che è l'unico modo perché restino coerenti.

## Iterare senza perdere il lavoro fatto

Dopo la prima generazione l'AI **non riscrive i file da capo**: applica modifiche
mirate a quelli che ci sono già. È il motivo per cui il layout, i colori e le
parti che non hai nominato restano come stavano.

Prima di ogni modifica dell'AI, Userbot salva un punto di ripristino della bozza.
Se una richiesta peggiora le cose, puoi tornare indietro dal pannello
**Versioni**. Se l'AI non riesce a modificare i file, lo dice (*«Non sono riuscito
ad applicare le modifiche. Riprova indicando cosa cambiare.»*) e il codice resta
quello di prima.

Il costruttore ricorda solo gli ultimi messaggi della conversazione. In una
sessione lunga, non dare per scontato che si ricordi una regola dichiarata venti
messaggi fa: riscrivila.

**Cancella chat builder** svuota i messaggi della conversazione di costruzione.
Il codice e le versioni restano: sparisce solo lo storico del dialogo.

## Se qualcosa non torna

#### L'anteprima è vuota

Compare appena descrivi la Mini App nella chat a sinistra. Se resta vuota dopo
una generazione, chiedi in chat di rigenerarla descrivendo cosa vedi.

#### Il risultato è giusto ma l'interfaccia è confusa

Chiedi le modifiche in termini di ciò che deve vedere chi la usa: quali campi
per primi, quale risultato in evidenza, quali etichette. L'AI lavora bene sulle
richieste concrete e male su «rendila più bella».

#### Il calcolo è sbagliato

Riscrivi la regola nella chat con un esempio numerico completo: dati in
ingresso e risultato atteso. Un esempio vale più di una spiegazione.

#### Ho chiesto una modifica e non è cambiato niente

Se compare *«Non sono riuscito ad applicare le modifiche»*, l'AI ha esaurito i
tentativi senza riuscire a toccare il punto giusto. Indica dove intervenire con
le parole che si leggono a schermo: *«l'etichetta Quantità deve diventare
Pezzi»* funziona meglio di *«cambia la seconda etichetta»*.

#### In anteprima funziona, in chat no

In chat si usa la versione pubblicata, non la bozza. Se non hai ancora
premuto **Pubblica** dopo le ultime modifiche, in chat vedi la versione
precedente. → [Pubblicare una Mini App](/pubblicare-miniapp)

#### Ho aggiunto un campo ma l'AI continua a non passarmelo

Apri **Parametri** e controlla che il campo ci sia davvero nello schema di
input. Se non c'è, l'AI ha cambiato l'interfaccia senza dichiararlo: chiedi in
chat di aggiungerlo ai parametri, nominandolo. Poi pubblica.

#### Non riesco a modificarla

Se in alto compare **Solo visualizzazione**, hai accesso in lettura e il campo
della chat è disattivato. Chiedi al Proprietario il ruolo di Editor, oppure
duplicala dal menu **⋯** e lavora sulla tua copia.