Environnements : local dev, staging, production + Dev Mode

1. Pourquoi se soucier des environnements

Dans le développement web classique, tôt ou tard apparaît un trio : développement local, serveur de test et environnement de production. Dans le monde des ChatGPT Apps, c’est pareil, avec une nuance supplémentaire : le client (ChatGPT) est toujours dans le cloud, même lorsque vous développez « en local ».

Si tout tourne uniquement sur votre ordinateur portable sous une adresse de tunnel aléatoire, plusieurs effets désagréables apparaissent. Premièrement, l’URL change en permanence et vous ne vous souvenez pas à quel endpoint le Dev Mode est actuellement relié. Deuxièmement, les performances et le réseau ne ressemblent pas aux conditions réelles. Troisièmement, l’environnement local utilise souvent d’autres clés, d’autres services et vit globalement dans une réalité parallèle.

À l’inverse, vivre « tout le temps en prod » est également une mauvaise idée. Toute modification peut soudainement casser des scénarios pour des utilisateurs réels, surtout si vous avez déjà des intégrations comme Stripe, OAuth ou des paiements via ACP. Sur le plan juridique et en termes de politique produit, c’est problématique aussi : expérimenter sur de vrais utilisateurs n’est pas le meilleur chemin vers le Store.

L’objectif de ce cours est donc de vous forger un schéma simple mais strict : il y a local dev, il y a staging, il y a production, et il y a le Dev Mode comme moyen d’aiguiller ChatGPT vers l’environnement voulu. Et non pas un grand « mon laptop avec un tunnel, qui se transforme parfois soudainement en prod ».

2. Particularité des ChatGPT Apps : le client est toujours dans le cloud

Dans une application SPA classique, vous lancez souvent à la fois le client et le serveur chez vous en local : le navigateur sur localhost, le backend sur localhost, et tout discute joyeusement dans une seule machine.

Avec les ChatGPT Apps, ce n’est pas le cas. Le client (ChatGPT + votre widget) vit toujours dans l’infrastructure OpenAI. Même si le code de votre application tourne sur votre ordinateur, la requête se déroule ainsi :

sequenceDiagram
    participant User as Utilisateur
    participant ChatGPT as ChatGPT (cloud)
    participant Tunnel as Tunnel HTTPS
    participant App as Votre Next.js + MCP

    User->>ChatGPT: Message / clic sur le widget
    ChatGPT->>Tunnel: Requête HTTPS vers l’URL de l’app
    Tunnel->>App: Proxy vers localhost
    App-->>Tunnel: Réponse (UI/JSON)
    Tunnel-->>ChatGPT: Réponse
    ChatGPT-->>User: Chat mis à jour + widget

Même lorsque vous « testez simplement en local », vous êtes déjà dans un système distribué : il y a un client dans le cloud, du réseau, un tunnel, et votre serveur local.

C’est important, parce que :

1. L’environnement local n’est pas « tout est chez moi en local ». C’est « cloud → tunnel → serveur local ».
2. Quand vous ajouterez plus tard le staging et la production, le schéma ne différera que par la destination des requêtes ChatGPT : vers le tunnel, vers le domaine de staging ou vers le domaine de prod.

3. Local dev : à quoi ressemble votre schéma actuel

Voyons à quoi ressemble ce schéma général chez vous maintenant.
Après les modules 2–6, vous avez probablement cette configuration :

• Un serveur de développement Next.js lancé avec la commande npm run dev (généralement http://localhost:3000).
• Un serveur MCP local (souvent un processus séparé, par exemple http://localhost:2091).
• Un tunnel HTTPS (ngrok, Cloudflare Tunnel, etc.) qui publie votre endpoint Next.js/HTTP vers l’extérieur à une adresse du type https://abc123.ngrok.app.

Via le Dev Mode dans ChatGPT, vous indiquez cette URL publique, et ChatGPT commence à interroger votre application. Tout cela constitue l’environnement local dev.

Propriétés principales du local dev :

• L’environnement local offre une boucle de feedback très rapide. Vous modifiez le code dans VS Code, Next.js fait un hot reload, le widget se met à jour en quelques secondes.
• Ici, vous pouvez tout casser, utiliser des données factices (mocks), des clés de test, des configurations étranges.
• Il n’y a pas d’utilisateurs réels ici, peu de gens en dehors de vous connaissent cette URL.

En général, cela ressemble à ceci :

graph LR
    subgraph Laptop de dev
      Next[Serveur dev Next.js]
      MCP[Serveur MCP]
    end

    ChatGPT((ChatGPT Cloud))
    Tunnel[[Tunnel HTTPS]]

    ChatGPT --> Tunnel --> Next
    Next --> MCP

Pour éviter de confondre local/staging/production, il est utile que l’application « sache » où elle s’exécute. Du point de vue du code, il est utile de fixer explicitement que vous êtes en environnement dev. La première étape la plus simple est d’introduire un petit module de configuration d’environnement.

Par exemple, créons le fichier app/config/env.ts :

// app/config/env.ts
export type AppEnv = 'local' | 'staging' | 'production';

export const APP_ENV: AppEnv =
  (process.env.NEXT_PUBLIC_APP_ENV as AppEnv) ?? 'local';

export const isProd = APP_ENV === 'production';

Ici, nous :

1. Introduisons un ensemble typé des environnements.
2. Lisons la variable NEXT_PUBLIC_APP_ENV (que vous renseignerez plus tard avec des valeurs différentes en dev/staging/prod).
3. Considérons par défaut que nous sommes en 'local', pour que le développement local fonctionne « out of the box ».

Cela ne déploie encore rien, mais fournit déjà un point d’ancrage : votre code sait dans quel environnement il s’exécute.

Ensuite, vous pouvez par exemple afficher l’environnement dans le widget lui‑même, pour éviter les confusions.

// app/components/EnvBadge.tsx
import { APP_ENV } from '../config/env';

export function EnvBadge() {
  return <span>ENV: {APP_ENV}</span>;
}

Un petit badge comme celui‑ci aide vraiment à ne pas confondre « suis‑je sur le staging ou en prod ? », surtout lorsque le widget est identique visuellement.

4. Staging : répétition générale de l’environnement de production

L’environnement de staging est une « répétition de l’environnement de production ». Ce n’est plus votre laptop avec le serveur de dev, mais un serveur distant ou un déploiement Vercel, sur lequel est poussé le code construit.

Du point de vue de ChatGPT, le staging ressemble presque à la production : c’est un endpoint HTTPS pratique et stable avec un domaine du type https://staging.giftgenius.app, où :

• le code est déjà construit (npm run build s’est terminé avec succès) ;
• des variables d’environnement proches de la prod sont utilisées (mêmes noms, même format), mais avec des clés de test ;
• les mêmes services externes sont accessibles (bac à sable Stripe, comptes OAuth de test) ;
• la topologie réseau est proche de la prod (par exemple, le même type de base de données et la même région).

Pourquoi le staging est utile dans le contexte des ChatGPT Apps :

Premièrement, c’est précisément sur le staging qu’il est pratique d’exécuter des scénarios de bout en bout. Par exemple : utilisateur dans ChatGPT → ChatGPT lance votre application → le widget pose des questions à l’utilisateur → un outil MCP est appelé et interroge une API externe → renvoie des recommandations → le widget affiche le résultat. Un tel scénario via un tunnel aléatoire en local peut se comporter d’une certaine manière, alors qu’en staging, c’est déjà différent : latence, réseau et ressources y sont plus proches de la réalité.

Deuxièmement, le staging permet de tester des intégrations qu’il est tout simplement effrayant de manipuler en local. Par exemple, les paiements : Stripe, ACP/Instant Checkout, etc. En staging, vous configurez des clés de test, des webhooks de test et vous déroulez des scénarios « grandeur nature » mais sans argent réel.

Troisièmement, le staging est un lieu de vérification par l’équipe. Si vous avez plusieurs développeurs, un designer, du QA, un product manager — ils ont besoin d’une URL commune indépendante du fait de savoir quel laptop est allumé et chez qui le tunnel a planté.

On peut se représenter le staging ainsi :

graph LR
    ChatGPT((ChatGPT Cloud))
    AppStaging["GiftGenius Staging  https://staging.giftgenius.app"]

    ChatGPT --> AppStaging

Et à l’intérieur de https://staging.giftgenius.app, vous pouvez faire tourner Next.js, un serveur MCP, une base de données de staging, etc.

Dans ce cours, nous ne détaillons pas le déploiement sur Vercel — ce sera l’objet des prochains thèmes. Pour l’instant, retenez simplement ceci : le staging est un environnement distinct, le plus proche possible de la production en termes de configuration et de mode d’accès depuis ChatGPT.

5. Production : serveur de prod et vrais utilisateurs

L’environnement de production est l’endroit où viennent de vrais utilisateurs et de l’argent réel. Ici, fini le « je corrige vite fait sur main pour voir ce que ça donne » — tout changement doit être réfléchi, testé et, si possible, réversible.

Le domaine de production doit être stable. Ce n’est pas une URL ngrok aléatoire, mais un nom propre du type https://giftgenius.app ou équivalent. C’est précisément cette adresse que vous indiquez dans les paramètres de l’App pour le Store : quand un utilisateur trouve votre application dans le ChatGPT Store et la lance, ChatGPT appellera cet endpoint.

On exige généralement davantage de l’environnement de production :

• Stabilité. Faible taux d’erreurs, temps de réponse prévisible, comportement correct sous charge. Nous parlerons des SLO/SLI dans des modules ultérieurs, mais intuitivement, « l’application doit fonctionner “presque toujours” et répondre “presque toujours” rapidement ».
• Sécurité. Uniquement les secrets nécessaires, des permissions minimales, un traitement soigneux des PII et de l’argent.
• Limitation des expérimentations. Pas de « j’ai relancé le serveur de dev » en pleine journée de travail ; expérimentez via des feature flags, de l’A/B testing ou un environnement dev/staging séparé, pas en bricolant directement le serveur de prod.

En termes de ChatGPT, la production — ce n’est plus une histoire de Dev Mode, mais celle d’une App publiée : elle est accessible aux utilisateurs via le Store ou les réglages d’organisation, passe un processus de review et doit être suffisamment fiable pour ne pas se ridiculiser devant la modération.

6. Dev Mode vs usage en prod de l’App : qui pointe vers quoi

Voici maintenant la confusion la plus fréquente : le Dev Mode de ChatGPT n’est pas un « environnement distinct ». C’est plutôt un sélecteur de routage : l’URL vers laquelle ChatGPT regarde au moment où vous testez l’application.

En Dev Mode, vous pouvez :

• brancher une application locale via un tunnel ;
• brancher l’environnement de staging ;
• voire temporairement pointer le Dev Mode vers la production (ce qui est en général à éviter).

Formellement, le Dev Mode dit à ChatGPT : « Voici le manifeste de mon App, voici l’URL de mon endpoint MCP/Apps SDK. Utilise‑la quand je lance cette application. » Et vous pouvez changer cette URL.

Après publication dans le Store, votre App obtient un endpoint officiel de production. C’est lui qui sera utilisé pour les utilisateurs réels, et vous ne pouvez pas le modifier à la légère : il faut une nouvelle version, une review, etc.

En pratique, un schéma raisonnable pour votre application d’apprentissage peut ressembler à ceci :

graph TD
    subgraph Dev Mode
      DevApp["GiftGenius Dev App
(Dev Mode)"]
    end

    subgraph Store
      ProdApp["GiftGenius
(Store App)"]
    end

    UserDev[Vous / l’équipe] --> DevApp
    UserProd[Utilisateurs réels] --> ProdApp

    DevApp -->|URL du tunnel| LocalEnv[Local dev
https://abc123.ngrok.app]
    DevApp -->|URL de staging| StagingEnv[Staging
https://staging.giftgenius.app]

    ProdApp -->|URL prod| ProdEnv[Production
https://giftgenius.app]

L’application en Dev Mode GiftGenius Dev est configurée pour regarder généralement vers le local dev (via un tunnel), et, quand nécessaire, vers le staging. L’application Store GiftGenius est liée strictement à l’URL de production.

Parfois, on crée aussi une App distincte pour la QA, du type GiftGenius Staging, qui regarde uniquement le staging. C’est pratique si vous avez une grande équipe de test ; dans le cadre du cours, un seul App de dev suffit.

Il est important de penser ainsi : le Dev Mode est un bac à sable personnel pour vous et votre équipe, où vous pouvez changer l’URL, modifier les métadonnées, redémarrer le tunnel. L’App de production dans le Store ne regarde que vers la production et vit selon des règles plus strictes.

7. Liaison des branches Git, des domaines et de l’App ChatGPT

Les environnements, ce ne sont pas que des serveurs. Ce sont aussi des branches de code et des configurations de l’App dans ChatGPT. Tôt ou tard, vous voudrez qu’un simple coup d’œil à l’URL ou au nom de l’App suffise pour comprendre quelle version du code y tourne.

Une approche minimale simple :

Pour développer des fonctionnalités, vous utilisez des branches feature/*, par exemple feature/new-recommendation-algo. Vous lancez le code en local + tunnel. Le Dev Mode de ChatGPT pointe en général vers le même endpoint de dev, où vous exécutez tour à tour vos versions locales. Créer une App séparée pour chaque branche feature serait excessif.

Pour l’intégration des fonctionnalités avant la release, vous pouvez créer une branche develop ou staging. Tout ce qui se trouve dans cette branche est déployé automatiquement vers l’environnement de staging, par exemple sur un URL de preview Vercel du type https://giftgenius-staging.vercel.app. Vous pouvez créer pour celui‑ci une App de Dev Mode dédiée ou reconfigurer périodiquement votre App de Dev Mode générale vers cette URL.

La branche main (ou master) ne contient que du code testé. C’est elle qui est déployée sur l’URL de production et liée à l’application Store GiftGenius.

Cela peut ressembler à peu près à ceci :

feature/*

https://abc123.ngrok.app

develop / staging

https://staging.gift...

main

https://giftgenius.app

Vous vous souvenez de APP_ENV dans app/config/env.ts ? Les valeurs 'local'/'staging'/'production' correspondent directement à la colonne « Environnement » : en local dev, vous lancez l’application avec APP_ENV=local, le déploiement de staging avec APP_ENV=staging, et la production avec APP_ENV=production.

Ce tableau n’est pas de la bureaucratie mais un moyen d’éviter le debugging à base de « quelle version tourne sur ce domaine, au juste ? ».

Dans le code lui‑même, vous pouvez renforcer légèrement ce lien. Par exemple, afficher non seulement ENV, mais aussi le commit/la branche dans le mode debug du widget :

// app/config/buildInfo.ts
export const BUILD_COMMIT = process.env.NEXT_PUBLIC_BUILD_COMMIT ?? 'dev';
export const BUILD_ENV = process.env.NEXT_PUBLIC_APP_ENV ?? 'local';

// app/components/BuildInfo.tsx
import { BUILD_COMMIT, BUILD_ENV } from '../config/buildInfo';

export function BuildInfo() {
  return <small>Build: {BUILD_ENV}@{BUILD_COMMIT}</small>;
}

Si, lors du déploiement, vous renseignez dans NEXT_PUBLIC_BUILD_COMMIT le SHA du commit, le widget affichera honnêtement quel code est en train de tourner. En staging/prod, cela peut parfois éviter des heures de debugging.

8. Mini‑pratique : dessiner le schéma de vos environnements

Avant de plonger dans Vercel et les logs, il est utile de « dessiner sur un coin de nappe » le schéma de vos environnements. Cela peut être un diagramme mermaid dans le README.md, un croquis sur un tableau ou même une image dans un carnet.

Pour notre GiftGenius pédagogique, le schéma peut ressembler à ceci :

graph TD
    subgraph ChatGPT
      DevMode["Dev Mode
(vous et l’équipe)"]
      Store["Store
(utilisateurs réels)"]
    end

    subgraph Servers
      Local[Local dev
Tunnel → localhost]
      Staging[Staging
staging.giftgenius.app]
      Prod[Production
giftgenius.app]
    end

    DevMode --> Local
    DevMode --> Staging
    Store --> Prod

Exercice utile pour vous juste après le cours :

1. Listez tous les environnements que vous avez déjà : local avec tunnel, peut‑être un premier déploiement Vercel, autre chose.
2. Indiquez à côté quelles branches Git s’y déploient.
3. Et à côté encore — quelles ChatGPT Apps (ou connecteurs) pointent vers où.
4. Ajoutez des flèches pour montrer d’où ChatGPT accède à chaque serveur.

Si vous ne travaillez pas seul, créez un fichier architecture/environments.md dans le dépôt. Cela réduira immédiatement la probabilité de « notre staging est tombé, mais personne ne sait quelle est l’URL ».

Pour relier cela à votre application, vous pouvez, dès maintenant en Dev Mode, créer une App GiftGenius Dev et décider : par défaut, elle pointe vers le tunnel de l’environnement local, et lorsque vous voulez tester une release complète, vous la reconfigurez temporairement vers l’URL de staging. Dans les prochains cours, vous apprendrez à déployer staging/prod sur Vercel et à relier cela aux variables d’environnement.

Pour résumer : considérez les environnements et le Dev Mode comme un système de coordonnées pour votre App. Le local est pour le développement rapide, le staging pour la répétition générale, la production pour les utilisateurs réels, et le Dev Mode est votre commutateur entre eux — pas un environnement magique séparé.

9. Erreurs courantes avec les environnements et le Dev Mode

Erreur n°1 : vivre uniquement sur localhost + tunnel et considérer que c’est la prod.
Cette approche paraît pratique : « à quoi bon le staging et la prod, mon tunnel marche, ChatGPT se connecte ». Mais le tunnel a une URL instable, des caractéristiques réseau différentes, et tout le schéma repose sur un seul laptop. Dès que vous aurez besoin de quelque chose comme un OAuth callback, des webhooks Stripe ou un MCP Gateway, l’absence d’un vrai staging/prod vous fera souffrir.

Erreur n°2 : confondre le Dev Mode avec un environnement séparé.
Beaucoup pensent : « j’ai un Dev Mode, donc j’ai un environnement dev ». En réalité, le Dev Mode dit juste à ChatGPT où aller : vers le tunnel, vers le staging, voire vers la prod. Le Dev Mode est un réglage côté client, pas côté serveur. Les environnements serveur (local/staging/prod), c’est vous qui les créez : déployez le code, configurez les domaines, les variables d’environnement.

Erreur n°3 : pointer le Dev Mode vers la production pour “tester un peu”.
Techniquement, c’est possible : vous pouvez mettre l’URL de production dans le Dev Mode et jouer avec votre App comme si c’était du local. Le problème, c’est que vous commencez soudain à tester sur de vrais utilisateurs, de vraies données et, potentiellement, de l’argent réel. La moindre erreur de l’outil ou du widget peut provoquer des incidents pour les utilisateurs en prod, et vous ne comprendrez pas tout de suite d’où cela vient. Mieux vaut garder le Dev Mode en dev/staging et utiliser l’App du Store pour la production.

Erreur n°4 : absence de carte explicite « branche ↔ environnement ↔ URL ↔ App ».
Si personne dans l’équipe ne peut dire du premier coup quelle branche est déployée sur le staging, quelle en est l’URL et quelle App ChatGPT pointe dessus, c’est une source de chaos garantie. On commence à entendre « chez moi ça marche, sur le staging non, et en prod c’est encore autre chose ». Un simple tableau ou un fichier markdown avec cette carte est vite rentabilisé.

Erreur n°5 : sous‑estimer la différence entre local dev et staging.
En local, vous lancez un serveur de dev, vous avez un ensemble de clés, un ensemble de services et un réseau donnés. En staging, le code est déjà construit, s’exécute dans un autre environnement, avec d’autres limites, d’autres timeouts et d’autres routes. Si vous testez tout uniquement en local et gardez le staging « pour la forme », les bugs critiques ressortiront déjà en prod. Il faut s’habituer à la chaîne : d’abord le développement local, ensuite la vérification en staging, et seulement après la release en production.

Erreur n°6 : tenter de résoudre tous les problèmes via ChatGPT en ignorant le schéma des environnements.
Parfois, en cas de problème, les développeurs commencent à « demander à ChatGPT ce qui s’est passé » au lieu de regarder le schéma : quelle App pointe vers quelle URL, dans quel environnement ça a planté, où sont les logs. Notre schéma des environnements d’aujourd’hui est le fondement du prochain cours, où nous déboguerons de manière systématique : regarder les logs, utiliser l’inspecteur MCP et seulement ensuite blâmer le modèle.