Scarichiamo e analizziamo ChatGPT App (Next.js 16)

1. Introduzione

L’obiettivo di questa lezione è semplice ma fondamentale: portarti da zero allo stato «ho una ChatGPT App funzionante in locale, vedo la pagina nel browser e non è caduto nulla».

Non andremo a scavare in profondità nel codice di Next.js, non configureremo il Dev Mode in ChatGPT e non apriremo ancora un tunnel — questo sarà oggetto delle prossime lezioni del modulo. Oggi ci concentriamo su tre cose:

1. Preparare l’ambiente: Node.js, npm, Git, editor, verifiche di base, in modo che Next.js 16 non vada in crash con la tua versione di Node.
2. Scaricare una ChatGPT App funzionante su Next.js 16: tramite git clone oppure tramite template/CLI di GitHub.
3. Installare le dipendenze, configurare .env con OPENAI_API_KEY e avviare npm run dev, assicurandoti che il tuo http://localhost:3000 sia vivo e vegeto.

Se alla fine della lezione vedrai la pagina iniziale del template nel browser e il dev server nel terminale senza errori in rosso — considera di avere già una ChatGPT App operativa.

2. Ambiente minimo di sviluppo

Partiamo dall’infrastruttura. Senza di essa nessuna LLM alla moda ti aiuterà — Next.js semplicemente non partirà.

Node.js e npm

Il template moderno di Apps SDK su Next.js 16 richiede una versione aggiornata di Node. Punta al ramo LTS — attualmente, ad esempio, Node 24 LTS. La versione minima accettabile è la 20.9, dalla quale Next.js 16 è ufficialmente supportato.

Controlliamo le versioni nel terminale:

node -v
npm -v

Se invece del comodo v24.x.x vedi, per esempio, v16.13.0, è molto probabile che il template non installerà neppure le dipendenze oppure Next.js si lamenterà: una versione di Node del genere non è supportata.

Puoi aggiornare «in modo semplice» — tramite l’installer ufficiale di Node.js per il tuo sistema operativo — oppure, se sei già un utente esperto Linux/Mac, tramite nvm/fnm. Nel corso non entreremo nelle complessità dei gestori di versioni; l’importante è ottenere una versione LTS funzionante.

Git

Ci servirà Git per ottenere il template e in futuro fare commit delle modifiche. Verifica:

git --version

Se il comando non viene trovato, devi installare Git (installer per Windows, Homebrew su macOS, gestore pacchetti su Linux). Per l’esecuzione dell’App Git non è critico, ma lavorare senza nel 2025 è un po’ come scrivere in TypeScript senza sapere cosa sia un’interfaccia.

Editor di codice

Raccomandazione predefinita — WebStorm. Per questo JavaRush ha un plugin dedicato, così puoi risolvere gli esercizi in pochi clic. Di fatto è lo standard de facto per il frontend e Node.

In alternativa puoi usare VS Code; in tal caso è consigliabile installare le estensioni di base:

• supporto TypeScript/JavaScript;
• ESLint (il template è spesso già configurato per il linter).

Questo ti semplificherà la vita quando inizieremo a modificare il codice del template.

Account OpenAI / ChatGPT e chiave API

Per questa lezione basta avere accesso a ChatGPT nel browser (con il tuo account). Collegheremo il Dev Mode più avanti, ma è già utile verificare che tu possa accedere all’interfaccia web e che ci sia la scheda con le funzionalità per sviluppatori (Plus/Team/Enterprise a seconda della politica attuale di OpenAI).

In futuro servirà una chiave OpenAI API (OPENAI_API_KEY). Il nostro primo progetto può avviarsi anche senza: la UI iniziale è completamente statica. Tuttavia useremo comunque la chiave già in questa lezione e la metteremo nel file .env — tra poco vedremo come farlo e perché così è più sicuro.

La chiave si ottiene nella dashboard di OpenAI, viene conservata come segreto, non finisce nel repository e in generale la trattiamo come il numero del passaporto, solo peggio.

3. Dove prendere una ChatGPT App funzionante

Ora — la parte più piacevole: prendiamo un progetto starter già pronto, già configurato come ChatGPT App.

Perché proprio questo progetto

È un progetto molto semplice su Next.js 16, che unisce due ruoli in un unico repository: widget UI e server MCP.

La struttura è già predisposta:

• c’è una pagina React che verrà renderizzata come widget;
• c’è un endpoint del server MCP a cui ChatGPT si collegherà per gli strumenti;
• c’è una configurazione pronta di Next.js (incluse impostazioni importanti come assetPrefix per il corretto caricamento degli asset nell’iframe di ChatGPT).

È decisamente meglio che costruire tutto da zero.

Opzione 1: clonare il repository Git

Il percorso più diretto:

git clone https://github.com/codegym-cc/chatgpt-apps-examples/helloworld my-chatgpt-app
cd my-chatgpt-app/01-chatgpt-app-helloworld

Il nome del repository potrebbe cambiare in futuro, quindi prima di copiare il comando ha senso verificare il link aggiornato nella documentazione ufficiale o nei commenti sotto questa lezione.

Il comando git clone creerà la cartella my-chatgpt-app con tutto il contenuto del template e un repository Git già impostato.

Opzione 2: pulsante «Use this template» su GitHub

Se vuoi avere subito un tuo repository su GitHub, puoi:

1. Aprire la pagina del template su GitHub.
2. Premere il pulsante «Use this template».
3. Creare, a partire dal template, il tuo repository, ad esempio username/study-buddy-chatgpt-app.
4. Clonare poi proprio il tuo repository.

In sostanza, il risultato è lo stesso: in locale avrai una cartella con il codice del template, ma il remote di Git punterà non al repository di CodeGym, bensì al tuo.

Opzione 3: template via CLI

Con ogni probabilità in futuro apparirà un CLI ufficiale di OpenAI, qualcosa del tipo:

npx create-openai-app@latest my-chatgpt-app

Per ora non c’è ancora, poiché le applicazioni per ChatGPT hanno appena iniziato a svilupparsi. Ma è molto possibile che, nel momento in cui leggi questa lezione, qualcosa del genere esista già. Un comando simile va cercato nella documentazione ufficiale dell’Apps SDK.

La logica è la stessa: il CLI scarica e predispone lo stesso template, o uno molto simile. È già successo per la creazione dei plugin per ChatGPT, quindi col tempo, credo, arriverà anche per le applicazioni.

4. Installazione delle dipendenze e primo sguardo al progetto

Supponiamo che tu abbia già la cartella my-chatgpt-app con il progetto funzionante. È ora di installare le dipendenze.

npm install

Entra nella cartella del progetto e installa le dipendenze:

cd my-chatgpt-app
npm install

Lo script leggerà package.json, dove sono già elencati i pacchetti necessari: Next.js, React, Tailwind, Apps SDK e MCP SDK (@modelcontextprotocol/sdk).

Alla fine comparirà la directory node_modules — quel mostro da centinaia di megabyte che non facciamo mai commit su Git. Di solito è già aggiunta a .gitignore nel template, quindi non serve configurare altro.

Se durante l’installazione delle dipendenze qualcosa fallisce, non farti prendere dal panico: affronteremo più sotto i problemi tipici.

Mini ispezione dei contenuti

Al momento non serve approfondire la struttura delle cartelle — è l’argomento della prossima lezione, dove analizzeremo in dettaglio cosa c’è e dove. Ma è utile dare almeno un’occhiata alla root del progetto:

• package.json — elenco delle dipendenze e degli script.
• next.config.ts — configurazione di Next.js con impostazioni aggiuntive per il funzionamento dentro ChatGPT.
• tsconfig.json — configurazione di TypeScript.
• app/ — qui vive il codice principale della UI e le route MCP.

La prossima volta trasformeremo questa «foresta oscura» in una mappa comprensibile.

5. Configurazione di .env e OPENAI_API_KEY

Abbiamo già menzionato che per il primo template non serve OPENAI_API_KEY, ma verrà utilizzata in futuro, quindi facciamo subito le cose per bene: tramite .env. Le persone serie non hardcodano i segreti nel codice — anche noi cercheremo di comportarci da persone serie.

A cosa serve .env

Nel template si usa il file d’ambiente .env.local, da cui Next.js carica le variabili d’ambiente.

Di solito nel repository c’è .env.example, oppure nel README è descritto quali variabili impostare. Nel nostro caso il minimo è OPENAI_API_KEY:

OPENAI_API_KEY=sk-la-tua-chiave-di-OpenAI

Si consiglia di usare proprio .env.local, per evitare che i segreti locali si confondano con le impostazioni di produzione.

È importante che .env.local sia già aggiunto a .gitignore, cioè Git non lo vedrà e non lo includerà accidentalmente in un commit. Controlla comunque che in .gitignore ci sia davvero la riga .env*.

Dove prendere e come conservare la chiave OpenAI API

La chiave API si crea nella console di OpenAI; di solito inizia con sk-. Poi si seguono le regole classiche di igiene IT:

• non pubblicare la chiave su GitHub e non inviarla in chat;
• non inserirla negli esempi di codice sui forum;
• in caso di sospetta fuga — ruotarla (la rotazione delle chiavi è tema dei moduli sulla sicurezza).

In questa lezione è importante solo che la chiave sia presente correttamente in .env.local e sia accessibile tramite process.env.OPENAI_API_KEY nella parte server quando servirà.

Particolarità per i diversi OS

Ci sono alcuni piccoli aspetti in cui è facile inciampare:

• Su Windows, se decidi di impostare le variabili d’ambiente non tramite .env, ma direttamente da riga di comando, dovrai usare set VAR=VALUE && comando, e non export.
• Assicurati che .env.local sia nella root del progetto e abbia il nome corretto: .env o .env.local, senza .txt o altri «miglioramenti» dell’editor.

6. Primo avvio: npm run dev e localhost:3000

Ora la parte più piacevole: verifichiamo che tutto si compili e che il progetto si avvii.

Avvio del server di sviluppo

Nella root del progetto esegui:

npm run dev

Questo comando avvia Next.js in modalità sviluppo. Nel terminale vedrai più o meno quanto segue:

• build del progetto (con Turbopack per un dev mode veloce);
• una riga del tipo Ready in Xs e il messaggio che il server ascolta sulla porta 3000;
• l’indirizzo http://localhost:3000 come URL locale.

Se appaiono messaggi in rosso — non fare subito scroll verso l’alto, prova a leggere: Next suggerisce piuttosto bene cosa gli manca (versione di Node, dipendenze, ecc.).

Apriamo nel browser

Poi apri nel browser:

http://localhost:3000

Se tutto è andato a buon fine, vedrai la pagina iniziale del progetto. Nelle varie versioni può apparire leggermente diversa, ma di solito c’è un titolo tipo «Your ChatGPT App» o una descrizione minima del widget.

A questo punto ci interessa solo una cosa: la pagina si apre, non cade con un errore 500 e non mostra un enorme stack trace.

Più avanti vedremo che il progetto può differenziare tra «homepage» (landing) e la pagina del widget, che viene realmente incorporata in ChatGPT tramite iframe. Ma per ora, per noi, l’intero sito è solo un modo molto costoso per mostrare «Hello, world».

Schema di ciò che accade

Per comprendere il quadro generale è utile guardare uno schema semplificato:

+-----------------------------+
|         Il tuo computer     |
|                             |
|  +-----------------------+  |
|  |  server di sviluppo   |  |
|  |  Next.js (npm run dev)|  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|      Browser (Chrome)       |
+-------------+---------------+

ChatGPT e il tunnel arriveranno più tardi — per ora comunichi direttamente con il Next.js locale tramite il browser.

Qui ChatGPT per ora non partecipa affatto. Ed è un bene: meno parti in movimento — più facile fare il debug.

7. Mini-diagnostica: cosa fare se qualcosa va storto

L’esperienza dimostra: se a qualcuno è partito tutto al primo colpo — probabilmente è già caduto tre volte con la stessa configurazione. Vediamo quindi i problemi tipici.

Porta 3000 occupata

Uno degli errori più frequenti: esegui npm run dev, e Next.js segnala qualcosa come EADDRINUSE: address already in use 0.0.0.0:3000. Significa che la porta 3000 è già occupata da un altro processo.

Possibili cause:

• in un altro terminale sta già girando npm run dev da questo o da un altro progetto;
• sulla stessa porta è in esecuzione un altro server (più raro, ma succede).

Soluzioni:

• trovare e terminare il processo precedente (spesso basta chiudere l’altro terminale con il dev server);
• avviare il server di sviluppo su un’altra porta, ad esempio:

PORT=3001 npm run dev

Su Windows la variante sarà così:

set PORT=3001 && npm run dev

Non dimenticare poi di aprire nel browser http://localhost:3001.

Node.js troppo vecchio

Se hai Node 16 o le prime versioni della 18, Next.js 16 potrebbe dirti chiaramente che tale Node non è supportato, oppure npm install potrebbe fallire per incompatibilità. La documentazione di Next 16 richiede Node non inferiore alla 20.9; meglio direttamente l’LTS recente.

In tal caso non ci sono alternative: devi aggiornare Node. È più veloce che provare ad aggirare i vincoli di Next.js 16. Dopo l’aggiornamento, a volte è utile eliminare la cartella node_modules e il lock file (package-lock.json) e rieseguire npm install, così le dipendenze si riallineano alla nuova versione.

Errori durante npm install

Se l’installazione delle dipendenze fallisce:

• assicurati che Internet funzioni e che registry.npmjs.org non sia bloccato da impostazioni locali;
• controlla la versione di Node (vedi sopra);
• quando cambi la versione di Node, ha senso ricostruire node_modules da zero.

Nella maggior parte dei casi il testo dell’errore nel terminale indica su quale pacchetto è avvenuto il crash e spesso scrive chiaramente: «serve Node >= X.Y.Z».

La variabile d’ambiente non viene letta

Capita che tutto si avvii, ma il server segnali che OPENAI_API_KEY non è impostata. Verifica con la checklist seguente:

• il file si chiama .env o .env.local, è nella root del progetto e Next.js lo vede;
• dopo aver aggiunto/modificato .env devi riavviare il dev server, altrimenti continuerà a vivere con i valori d’ambiente vecchi;
• la variabile si chiama esattamente OPENAI_API_KEY, senza refusi.

Se vuoi solo vedere la pagina del progetto, puoi temporaneamente commentare o disattivare le parti di codice che richiedono la chiave, ma nel corso è meglio imparare subito a gestire correttamente i segreti.

Dove vedere log ed errori

Tutti gli errori di build e runtime di Next.js in dev mode vengono stampati nello stesso terminale in cui hai avviato npm run dev. In questa fase il codice è ancora poco, quindi i problemi tipici sono — dipendenza mancante, .env sbagliato o Node troppo vecchio.

Apri anche i DevTools del browser (F12):

• la scheda Console ti segnalerà se c’è qualcosa che non va nel frontend;
• Network mostrerà se alcune richieste verso /mcp o verso gli asset statici falliscono (ci tornerà utile più avanti quando collegheremo ChatGPT).

Ora che sai dove cercare errori e log, mettiamo tutto insieme in un breve scenario pratico.

8. Un po’ di pratica: la tua prima ChatGPT App è già in esecuzione

Mettiamo tutto insieme in un piccolo scenario pratico.

1. Verifica che node -v mostri almeno 20.9, meglio 22+.
2. Verifica che git --version e npm -v rispondano.
3. Clona il template ufficiale nella cartella study-buddy-app (o come vuoi chiamare la tua futura App).
4. Nella cartella esegui npm install.
5. Crea .env.local con OPENAI_API_KEY=....
6. Esegui npm run dev e apri http://localhost:3000 nel browser.

Se è andato tutto a buon fine — puoi considerare di avere già la ChatGPT App più semplice, anche se per ora non collegata a ChatGPT.

Per «toccare con mano» un po’ di codice, puoi aprire nell’editor il componente React principale della pagina (di solito è app/page.tsx) e vedere qualcosa di molto simile a questo:

export default function Page() {
  return (
    <main>
      <h1>HelloWorld — ChatGPT App</h1>
      <p>Two actions only: fetch data from <code>/api/time</code> and open an external link.</p>
    </main>
  );
}

Non è necessario toccarlo adesso — in una delle prossime lezioni analizzeremo con cura la struttura del progetto e inizieremo ad adattarlo al nostro scenario didattico.

9. Errori tipici nello scaricare e avviare il template

Errore n. 1: usare un repository «a caso» invece del progetto ufficiale.
A volte gli studenti trovano su GitHub qualche «starter fantastico per ChatGPT» e iniziano il corso da lì. Il problema è che struttura, versioni di Next.js e Apps SDK possono differire molto dal progetto ufficiale su cui si basa il corso. Nell’ambito di questo corso prima impariamo il progetto ufficiale, poi sperimentiamo con template altrui.

Errore n. 2: ignorare i requisiti della versione di Node.js.
«Mi funziona tutto su Node 16 da tre anni, perché aggiornare?» — dice lo sviluppatore e poi passa un’ora a leggere strani errori di build. Next.js 16 e l’Apps SDK moderno richiedono una versione recente di Node, e non è un capriccio degli autori del corso: è scritto chiaramente nella documentazione di Next.js.

Errore n. 3: fare commit di .env e node_modules nel repository.
Un classico. Se per errore rimuovi .env o node_modules da .gitignore e fai commit di tutto su GitHub, nel migliore dei casi ti rimprovereranno in code review, nel peggiore — trapelerà la OPENAI_API_KEY. Il template è già impostato per evitarlo, ma è sempre utile controllare il contenuto di .gitignore e non modificarlo senza necessità.

Errore n. 4: dimenticare di riavviare il dev server dopo aver modificato .env.
Next.js legge le variabili d’ambiente all’avvio del processo. Se hai aggiunto OPENAI_API_KEY in .env.local ma non hai riavviato npm run dev, il server continuerà a vivere con i vecchi valori vuoti e ti chiederai perché la chiave «non è visibile». In pratica è una delle cause più frequenti di confusione, quindi non dimenticare di riavviare il dev server dopo modifiche a .env.

Errore n. 5: cercare di risolvere problemi di sincronizzazione e porte con «riavvii magici» dell’IDE.
A volte, in caso di conflitto di porta o versione sbagliata di Node, gli sviluppatori iniziano a chiudere/aprire l’editor, riavviare il computer, pregare, ecc. Il problema di solito si risolve in modo molto più prosaico: liberare la porta 3000, aggiornare Node e rileggere il testo dell’errore nel terminale. Il dev server scrive piuttosto onestamente ciò che non gli piace — basta non essere pigri e leggerlo.