Téléchargement et prise en main de ChatGPT App (Next.js 16)

1. Introduction

L’objectif de cette leçon est simple mais essentiel : vous amener du point zéro à l’état « j’ai une ChatGPT App qui tourne en local, je vois la page dans le navigateur et rien n’a planté ».

Nous n’allons pas disséquer en profondeur le code Next.js, nous n’allons pas configurer le Dev Mode dans ChatGPT, et nous n’allons pas encore mettre en place de tunnel — ce sera pour les prochaines leçons du module. Aujourd’hui, on se concentre sur trois choses :

1. Préparer l’environnement : Node.js, npm, Git, éditeur, vérifications de base, pour que Next.js 16 ne casse pas avec votre version de Node.
2. Télécharger une ChatGPT App fonctionnelle sur Next.js 16 : soit via git clone, soit via un template/CLI GitHub.
3. Installer les dépendances, configurer le .env avec OPENAI_API_KEY et lancer npm run dev, en vérifiant que votre http://localhost:3000 est bien vivant.

Si, à la fin de la leçon, vous voyez la page d’accueil du template dans le navigateur et le serveur de dev dans le terminal sans messages d’erreur en rouge — considérez que vous avez déjà votre ChatGPT App opérationnelle.

2. Environnement minimal du développeur

Commençons par l’infrastructure. Sans elle, même les LLM les plus à la mode ne vous aideront pas — Next.js ne démarrera tout simplement pas.

Node.js et npm

Le template actuel d’Apps SDK sur Next.js 16 exige une version récente de Node. Visez la branche LTS — actuellement, par exemple, Node 24 LTS. La version minimale acceptable est 20.9, à partir de laquelle Next.js 16 est officiellement pris en charge.

Vérifiez les versions dans le terminal :

node -v
npm -v

Si, au lieu d’un joli v24.x.x, vous voyez, disons, v16.13.0, il y a de fortes chances que le template n’installe même pas les dépendances ou que Next.js râle : cette version de Node n’est pas prise en charge.

La mise à jour peut se faire « simplement » — via l’installeur officiel de Node.js pour votre OS — ou, si vous êtes déjà un utilisateur Linux/macOS aguerri, via nvm/fnm. Dans le cadre du cours, nous n’entrerons pas dans les détails des gestionnaires de versions ; l’essentiel est d’obtenir une LTS fonctionnelle.

Git

Nous aurons besoin de Git pour récupérer le template et, plus tard, commiter vos modifications. Vérification :

git --version

Si la commande est introuvable, il faut installer Git (installeur Windows, Homebrew sur macOS, gestionnaire de paquets sur Linux). Pour démarrer l’app, Git n’est pas critique, mais travailler sans en 2025, c’est un peu comme écrire du TypeScript sans savoir ce qu’est une interface.

Éditeur de code

Recommandation par défaut — WebStorm. JavaRush propose un plugin dédié pour résoudre les exercices en quelques clics. En pratique, c’est le « standard de facto » pour le frontend et Node.

Vous pouvez bien sûr utiliser VS Code ; dans ce cas, installez idéalement les extensions de base :

• prise en charge de TypeScript/JavaScript ;
• ESLint (le template est souvent déjà configuré pour le linter).

Cela vous facilitera la vie lorsque nous commencerons à modifier le code du template.

Compte OpenAI/ChatGPT et clé API

Pour cette leçon, il suffit d’avoir accès à ChatGPT dans le navigateur (avec votre compte). Nous activerons le Dev Mode plus tard, mais assurez‑vous dès maintenant que vous pouvez ouvrir l’interface web et qu’il existe un onglet avec des fonctionnalités développeur (Plus/Team/Enterprise selon la politique actuelle d’OpenAI).

À l’avenir, une clé OpenAI API (OPENAI_API_KEY) sera nécessaire. Notre premier projet peut démarrer sans : l’UI initiale est entièrement statique. Mais nous allons quand même utiliser la clé dès cette leçon et la placer dans un fichier .env — nous verrons un peu plus bas comment faire et pourquoi c’est plus sûr.

La clé se récupère dans le tableau de bord OpenAI, se conserve comme un secret, ne va pas dans le dépôt et, de manière générale, on la traite comme un numéro de passeport — en pire.

3. Où récupérer une ChatGPT App fonctionnelle

Passons maintenant au plus agréable : nous prenons un projet de démarrage prêt à l’emploi, déjà configuré en ChatGPT App.

Pourquoi ce projet en particulier

C’est un projet très simple sur Next.js 16 qui réunit deux rôles dans un seul dépôt : un widget UI et un serveur MCP.

La structure est déjà préparée :

• il y a une page React qui sera rendue comme widget ;
• il y a un endpoint de serveur MCP auquel ChatGPT se connectera pour les outils ;
• il y a une configuration Next.js prête (y compris des détails importants comme assetPrefix pour charger correctement les assets dans l’iframe de ChatGPT).

C’est bien mieux que de tout assembler à partir de zéro.

Option 1 : cloner le dépôt Git

La voie la plus directe :

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

Le nom du dépôt peut légèrement évoluer à l’avenir ; avant de copier la commande, vérifiez le lien actuel dans la documentation officielle ou dans les commentaires sous cette leçon.

La commande git clone créera chez vous le dossier my-chatgpt-app avec tout le contenu du template et un dépôt Git déjà initialisé.

Option 2 : bouton « Use this template » sur GitHub

Si vous voulez avoir immédiatement votre propre dépôt sur GitHub, vous pouvez :

1. Ouvrir la page du template sur GitHub.
2. Cliquer sur le bouton « Use this template ».
3. Créer votre dépôt à partir du template, par exemple username/study-buddy-chatgpt-app.
4. Cloner ensuite précisément votre dépôt.

En pratique, le résultat est le même : vous aurez localement un dossier avec le code du template, mais le remote Git pointera non pas vers le dépôt de CodeGym, mais vers le vôtre.

Option 3 : modèle via CLI

Il est probable qu’un outil CLI officiel d’OpenAI apparaisse à l’avenir, quelque chose comme :

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

Pour l’instant, il n’existe pas encore, car les applications pour ChatGPT commencent tout juste à se développer. Mais il se peut très bien qu’au moment où vous lisez cette leçon, quelque chose de ce genre soit déjà disponible. Cette commande est à rechercher dans la documentation officielle d’Apps SDK.

La logique est la même : le CLI télécharge et déploie le même template ou un template très proche. C’était déjà le cas pour créer des plugins pour ChatGPT, donc il y a fort à parier que l’équivalent pour les applications arrivera.

4. Installation des dépendances et premier coup d’œil au projet

Supposons que vous avez déjà le dossier my-chatgpt-app avec un projet fonctionnel. Il est temps d’installer les dépendances.

npm install

Allez dans le dossier du projet et installez les dépendances :

cd my-chatgpt-app
npm install

Le script lira package.json, où les paquets nécessaires sont déjà définis : Next.js, React, Tailwind, Apps SDK et MCP SDK (@modelcontextprotocol/sdk).

Un répertoire node_modules apparaîtra — ce fameux monstre de plusieurs centaines de mégaoctets que nous ne commettons jamais dans Git. Il est généralement déjà ajouté à .gitignore dans le template, donc rien à configurer en plus.

Si quelque chose échoue pendant l’installation des dépendances, pas de panique : nous verrons un peu plus bas les problèmes typiques.

Mini‑inspection du contenu

Pour l’instant, il ne faut pas creuser la structure des dossiers — ce sera l’objet de la leçon suivante, où nous détaillerons qui se trouve où. Mais il est utile de jeter un œil à la racine du projet :

• package.json — liste des dépendances et des scripts.
• next.config.ts — config Next.js avec des réglages supplémentaires pour fonctionner dans ChatGPT.
• tsconfig.json — configuration TypeScript.
• app/ — là où vit le code principal de l’UI et les routes MCP.

La prochaine fois, nous transformerons cette « forêt sombre » en carte compréhensible.

5. Configuration de .env et de OPENAI_API_KEY

Nous avons déjà mentionné qu’une OPENAI_API_KEY n’est pas nécessaire pour le premier template, mais elle sera utilisée par la suite, donc faisons les choses correctement dès maintenant : via .env. Les gens sérieux ne hardcodent pas les secrets dans le code — faisons de même.

Pourquoi utiliser .env

Le template utilise un fichier d’environnement .env.local, à partir duquel Next.js récupère les variables d’environnement.

En général, le dépôt contient soit un .env.example, soit le README explique quelles variables définir. Dans notre cas, le minimum sera OPENAI_API_KEY :

OPENAI_API_KEY=sk-votre-clé-OpenAI

On recommande d’utiliser précisément .env.local pour éviter que les secrets locaux se mélangent aux réglages de production.

Important : .env.local est déjà ajouté à .gitignore, donc Git ne le verra pas et ne l’ajoutera pas par erreur à un commit. Vérifiez tout de même que .gitignore contient bien une ligne .env*.

Où obtenir et comment stocker la clé OpenAI API

La clé API se crée dans la console OpenAI ; elle commence généralement par sk-. Appliquez ensuite les règles classiques d’hygiène IT :

• ne publiez pas la clé sur GitHub et ne l’envoyez pas dans des chats ;
• ne l’insérez pas dans des exemples de code sur des forums ;
• en cas de suspicion de fuite — changez‑la (la rotation des clés sera abordée dans les modules sécurité).

Dans cette leçon, il nous suffit de nous assurer que la clé est correctement présente dans .env.local et accessible via process.env.OPENAI_API_KEY côté serveur lorsque nécessaire.

Nuances selon les OS

Voici quelques petits écueils fréquents :

• Sur Windows, si vous décidez de définir les variables d’environnement non pas via .env mais directement en ligne de commande, il faudra utiliser set VAR=VALUE && commande, et non export.
• Vérifiez que .env.local est à la racine du projet et porte le bon nom : .env ou .env.local, sans .txt ni autres « améliorations » de l’éditeur.

6. Premier lancement : npm run dev et localhost:3000

Passons maintenant au plus agréable : vérifions que tout compile et que le projet démarre.

Lancer le serveur de développement

À la racine du projet, exécutez :

npm run dev

Cette commande lance Next.js en mode développement. Dans le terminal, vous verrez à peu près ceci :

• la compilation du projet (avec Turbopack pour un mode dev rapide) ;
• une ligne du type Ready in Xs et un message indiquant que le serveur écoute sur le port 3000 ;
• l’adresse http://localhost:3000 comme URL locale.

Si des messages d’erreur en rouge apparaissent — ne faites pas défiler vers le haut tout de suite ; essayez de lire : Next indique plutôt bien ce qui lui manque (version de Node, dépendances, etc.).

Ouvrir dans le navigateur

Ensuite, ouvrez dans le navigateur :

http://localhost:3000

Si tout s’est bien passé, vous verrez la page d’accueil du projet. Selon les versions, elle peut varier un peu, mais on y trouve généralement un en‑tête du genre « Your ChatGPT App » ou une description minimale du widget.

À ce stade, une seule chose compte : la page s’ouvre, ne tombe pas avec une erreur 500 et n’affiche pas une énorme stacktrace.

Plus tard, nous verrons qu’il peut y avoir une différence entre la « page d’accueil » (landing) et la page du widget réellement intégrée à ChatGPT via un iframe. Pour l’instant, le site est juste une manière très coûteuse d’afficher « Hello, world ».

Schéma de ce qui se passe

Pour comprendre le tableau d’ensemble, regardez ce schéma simplifié :

+-----------------------------+
|      Votre ordinateur       |
|                             |
|  +-----------------------+  |
|  |  serveur de dev       |  |
|  |  Next.js (npm run dev)|  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|   Navigateur (Chrome)       |
+-------------+---------------+

ChatGPT et le tunnel arriveront plus tard — pour l’instant, vous communiquez directement avec Next.js en local via le navigateur.

ChatGPT n’intervient pas encore ici. Et c’est très bien : moins de pièces mobiles — plus simple à déboguer.

7. Mini‑diagnostic : que faire si quelque chose ne va pas

L’expérience montre que si tout a fonctionné du premier coup chez quelqu’un — c’est probablement parce qu’il s’est déjà planté trois fois avec la même configuration. Voyons donc les problèmes typiques.

Le port 3000 est occupé

L’une des erreurs les plus courantes : vous lancez npm run dev et Next.js se plaint de quelque chose comme EADDRINUSE: address already in use 0.0.0.0:3000. Cela signifie que le port 3000 est déjà occupé par un autre processus.

Causes possibles :

• quelque part dans un autre terminal tourne déjà un npm run dev (de ce projet ou d’un autre) ;
• un autre serveur écoute sur le même port (plus rare, mais ça arrive).

Solutions :

• trouver et tuer l’ancien processus (souvent, fermer l’autre terminal avec le serveur de dev suffit) ;
• lancer le serveur de dev sur un autre port, par exemple :

PORT=3001 npm run dev

Sur Windows, la variante ressemble à ceci :

set PORT=3001 && npm run dev

N’oubliez pas d’ouvrir ensuite http://localhost:3001 dans le navigateur.

Node.js trop ancien

Si vous avez Node 16 ou un 18 ancien, Next.js 16 peut indiquer clairement que cette version n’est pas prise en charge, ou bien npm install échouera avec une erreur d’incompatibilité. La documentation de Next 16 exige Node au moins en 20.9, et idéalement la dernière LTS.

Dans ce cas, pas d’alternative : il faut mettre à jour Node. C’est plus rapide que d’essayer de contourner les contraintes de Next.js 16. Après mise à jour, il peut être utile de supprimer le dossier node_modules et le fichier lock (package-lock.json), puis de relancer npm install pour réaligner les dépendances.

Erreurs lors de npm install

Si l’installation des dépendances échoue :

• assurez‑vous que la connexion Internet fonctionne et que registry.npmjs.org n’est pas bloqué par des réglages locaux ;
• vérifiez la version de Node (voir ci‑dessus) ;
• après un changement de version de Node, il est pertinent de reconstruire node_modules à partir de zéro.

Dans la plupart des cas, le message d’erreur dans le terminal indique sur quel paquet tout a échoué, et précise souvent : « nécessite Node >= X.Y.Z ».

La variable d’environnement n’est pas prise en compte

Il arrive que tout démarre, mais que le serveur se plaigne que OPENAI_API_KEY n’est pas définie. Vérifiez la checklist ci‑dessous :

• le fichier s’appelle .env ou .env.local, est à la racine du projet et Next.js le voit ;
• après avoir ajouté/modifié .env, il faut redémarrer le serveur de dev ; sinon, il continuera de tourner avec les anciennes valeurs ;
• la variable s’appelle exactement OPENAI_API_KEY, sans faute de frappe.

Si vous voulez seulement voir la page du projet, vous pouvez temporairement commenter ou désactiver les parties de code qui exigent la clé, mais dans le cadre du cours mieux vaut apprendre tout de suite à stocker les secrets correctement.

Où consulter les logs et les erreurs

Toutes les erreurs de build et d’exécution de Next.js en mode dev s’affichent dans le même terminal où vous avez lancé npm run dev. À ce stade, il y a encore peu de code, donc les problèmes typiques sont : dépendance manquante, .env incorrect, ou version de Node trop ancienne.

Ouvrez également les DevTools du navigateur (F12) :

• l’onglet Console vous alertera si quelque chose cloche côté frontend ;
• Network montrera si des requêtes vers /mcp ou la statique échouent (cela nous servira plus tard, quand nous brancherons ChatGPT).

Maintenant que vous savez où chercher erreurs et logs, réunissons tout cela dans un court scénario pratique.

8. Petit exercice : votre première ChatGPT App est déjà lancée

Rassemblons tout sous la forme d’un petit scénario pratique.

1. Vérifiez que node -v affiche au moins 20.9, idéalement 22+.
2. Vérifiez que git --version et npm -v répondent.
3. Clonez le template officiel dans le dossier study-buddy-app (ou comme vous souhaitez nommer votre future app).
4. Dans ce dossier, lancez npm install.
5. Créez .env.local avec OPENAI_API_KEY=....
6. Lancez npm run dev et ouvrez http://localhost:3000 dans le navigateur.

Si tout a fonctionné — considérez que vous avez déjà la ChatGPT App la plus simple, même si elle n’est pas encore connectée à ChatGPT.

Pour « toucher » un peu le code, vous pouvez ouvrir dans l’éditeur le composant React principal de la page (généralement app/page.tsx) et y voir quelque chose de très proche de ce code :

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>
  );
}

Pas besoin d’y toucher tout de suite — dans l’une des prochaines leçons, nous détaillerons la structure du projet et commencerons à l’adapter à notre scénario pédagogique.

9. Erreurs courantes lors du téléchargement et du lancement du template

Erreur n°1 : utiliser un dépôt « non officiel » au lieu du projet officiel.
Parfois, des étudiants trouvent sur GitHub un « super starter pour ChatGPT » et démarrent le cours avec. Le problème, c’est que la structure, les versions de Next.js et d’Apps SDK peuvent être très différentes de celles du projet officiel sur lequel s’appuie le cours. Dans ce cours, nous commençons par maîtriser le projet officiel, puis nous expérimentons avec d’autres templates.

Erreur n°2 : ignorer les exigences de version de Node.js.
« Tout marche chez moi sur Node 16 depuis trois ans, pourquoi mettre à jour ? » — dit le développeur, puis passe une heure à lire d’étranges erreurs de build. Next.js 16 et l’Apps SDK moderne exigent un Node récent, et ce n’est pas un caprice des auteurs du cours : c’est indiqué noir sur blanc dans la documentation de Next.js.

Erreur n°3 : committer .env et node_modules dans le dépôt.
C’est un grand classique. Si, par erreur, vous retirez .env ou node_modules de .gitignore et committez le tout sur GitHub, au mieux on vous fera la morale en review, au pire votre OPENAI_API_KEY fuitera. Le template est déjà configuré pour éviter cela, mais vérifiez toujours le contenu de .gitignore et ne le modifiez pas sans nécessité.

Erreur n°4 : oublier de redémarrer le serveur de dev après modification de .env.
Next.js lit les variables d’environnement au démarrage du processus. Si vous ajoutez OPENAI_API_KEY dans .env.local mais ne redémarrez pas npm run dev, le serveur continuera de vivre avec des valeurs anciennes/vides, et vous vous demanderez pourquoi la clé « n’est pas visible ». En pratique, c’est l’une des causes les plus fréquentes de confusion ; pensez donc à redémarrer le serveur de dev après des changements dans .env.

Erreur n°5 : tenter de résoudre les problèmes de synchro et de ports par des redémarrages « magiques » de l’IDE.
Parfois, face à un conflit de port ou une version de Node incorrecte, les développeurs se mettent à fermer/rouvrir l’éditeur, redémarrer l’ordinateur, prier, etc. Le problème se résout généralement de manière beaucoup plus prosaïque : libérer le port 3000, mettre à jour Node et relire le message d’erreur dans le terminal. Le serveur de dev explique assez honnêtement ce qui ne lui plaît pas — il suffit de prendre le temps de le lire.