Descargamos y analizamos ChatGPT App (Next.js 16)

1. Introducción

El objetivo de esta lección es sencillo pero vital: llevarte de cero al estado «tengo una ChatGPT App funcionando en local, veo la página en el navegador y nada se ha caído».

No vamos a meternos a fondo en el código de Next.js, no vamos a configurar el Dev Mode en ChatGPT ni a levantar aún un túnel — eso vendrá en las siguientes lecciones del módulo. Hoy nos centramos en tres cosas:

1. Preparar el entorno: Node.js, npm, Git, editor y comprobaciones básicas para que Next.js 16 no «muera» con tu versión de Node.
2. Descargar una ChatGPT App funcional en Next.js 16: o bien con git clone, o bien mediante una plantilla/CLI de GitHub.
3. Instalar dependencias, configurar .env con OPENAI_API_KEY y arrancar npm run dev, comprobando que tu http://localhost:3000 está vivo y sano.

Si al final de la lección ves la página inicial de la plantilla en el navegador y el servidor de desarrollo en la terminal sin errores en rojo, considera que ya tienes tu propia ChatGPT App operativa.

2. Entorno mínimo de desarrollo

Empecemos por la infraestructura. Sin ella, ninguna LLM moderna te ayudará — Next.js simplemente no arrancará.

Node.js y npm

La plantilla moderna de Apps SDK en Next.js 16 requiere una versión actual de Node. Apunta a la rama LTS — ahora, por ejemplo, Node 24 LTS. La versión mínima aceptable es la 20.9; a partir de ella Next.js 16 está oficialmente soportado.

Comprobamos las versiones en la terminal:

node -v
npm -v

Si en lugar de un v24.x.x pulcro ves, digamos, v16.13.0, es muy probable que la plantilla ni siquiera instale dependencias o que Next.js se queje: esa versión de Node no está soportada.

Puedes actualizarte «a lo sencillo» — con el instalador oficial de Node.js para tu SO — o, si ya eres un usuario avanzado de Linux/macOS, mediante nvm/fnm. En el curso no entraremos en los pormenores de los gestores de versiones; lo importante es conseguir una versión LTS funcional.

Git

Necesitaremos Git para obtener la plantilla y, en el futuro, hacer commit de tus cambios. Comprobación:

git --version

Si no se encuentra el comando, debes instalar Git (instalador para Windows, Homebrew en macOS, gestor de paquetes en Linux). Para ejecutar la App en sí Git no es crítico, pero trabajar sin él en 2025 es como programar en TypeScript sin saber qué es una interfaz.

Editor de código

La recomendación por defecto es WebStorm. JavaRush tiene un plugin específico para que puedas resolver tareas en un par de clics. De facto es el «estándar» para frontend y Node.

En principio puedes usar VS Code; en ese caso, conviene instalar extensiones básicas:

• soporte para TypeScript/JavaScript;
• ESLint (la plantilla suele venir ya configurada para el linter).

Esto te facilitará la vida cuando empecemos a modificar el código de la plantilla.

Cuenta de OpenAI / ChatGPT y clave de API

Para esta lección basta con tener acceso a ChatGPT en el navegador (con tu cuenta). Conectaremos el Dev Mode más adelante, pero es buena idea asegurarte ya de que puedes entrar a la interfaz web y de que existe una pestaña con funciones para desarrolladores (Plus/Team/Enterprise según la política vigente de OpenAI).

En el futuro necesitaremos la clave de API de OpenAI (OPENAI_API_KEY). Nuestro primer proyecto puede levantarse incluso sin ella: la UI inicial es totalmente estática. Aun así, vamos a usar la clave ya en esta lección y la pondremos en el archivo .env — un poco más abajo veremos cómo hacerlo y por qué es más seguro.

La clave se obtiene en el panel de OpenAI, se guarda como secreto, no entra en el repositorio y, en general, la tratamos como si fuera el número del pasaporte, solo que peor.

3. Dónde conseguir una ChatGPT App funcional

Ahora viene lo agradable: tomamos un proyecto inicial ya listo que está configurado como ChatGPT App.

Por qué precisamente este proyecto

Es un proyecto muy sencillo en Next.js 16 que reúne dos roles en un único repositorio: el widget de UI y el servidor MCP.

Estructura ya preparada:

• hay una página React que se renderiza como widget;
• hay un endpoint del servidor MCP al que ChatGPT llamará para las herramientas;
• hay una configuración de Next.js ya lista (incluyendo detalles importantes como assetPrefix para la carga correcta de assets en el iframe de ChatGPT).

Es mucho mejor que montarlo todo desde cero.

Opción 1: clonar el repositorio Git

El camino más directo:

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

El nombre del repositorio puede variar ligeramente en el futuro; por eso, antes de copiar el comando, conviene contrastarlo con el enlace actualizado en la documentación oficial o en los comentarios bajo esta lección.

El comando git clone creará en tu máquina la carpeta my-chatgpt-app con todo el contenido de la plantilla y el repositorio Git ya configurado.

Opción 2: botón «Use this template» en GitHub

Si quieres tener tu propio repositorio en GitHub desde el principio, puedes:

1. Abrir la página de la plantilla en GitHub.
2. Pulsar el botón «Use this template».
3. Crear tu repositorio a partir de la plantilla, por ejemplo username/study-buddy-chatgpt-app.
4. Y luego clonar tu propio repositorio.

En esencia, el resultado es el mismo: tendrás localmente una carpeta con el código de la plantilla, pero el remoto de Git apuntará a tu repositorio, no al de CodeGym.

Opción 3: plantilla por CLI

Es muy probable que en el futuro aparezca una herramienta CLI oficial de OpenAI, algo como:

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

De momento no existe, ya que las aplicaciones para ChatGPT acaban de empezar a evolucionar. Pero bien puede ser que cuando leas esta lección, ya haya algo así. Hay que buscar obligatoriamente ese tipo de comando en la documentación oficial del Apps SDK.

La lógica será la misma: el CLI solo descarga y despliega la misma plantilla o una muy similar. Ya pasó con la creación de plugins para ChatGPT, así que, con el tiempo, seguramente aparecerá también para aplicaciones.

4. Instalación de dependencias y primera mirada al proyecto

Supongamos que ya tienes la carpeta my-chatgpt-app con el proyecto funcional. Es hora de instalar las dependencias.

npm install

Entramos en la carpeta del proyecto e instalamos las dependencias:

cd my-chatgpt-app
npm install

El script leerá package.json, donde ya están definidos los paquetes necesarios: Next.js, React, Tailwind, Apps SDK y MCP SDK (@modelcontextprotocol/sdk).

Como resultado aparecerá el directorio node_modules — ese monstruo de cientos de megabytes que nunca comiteamos en Git. Suele estar ya añadido a .gitignore en la plantilla, así que no hay que configurar nada adicional.

Si durante la instalación de dependencias algo falla, no entres en pánico: más abajo veremos los problemas típicos.

Mini inspección del contenido

Ahora no hace falta profundizar en la estructura de carpetas — ese es el tema de la próxima lección, donde analizaremos en detalle qué hay y dónde. Pero es útil al menos echar un vistazo a la raíz del proyecto:

• package.json — lista de dependencias y scripts.
• next.config.ts — config de Next.js con ajustes adicionales para funcionar dentro de ChatGPT.
• tsconfig.json — configuración de TypeScript.
• app/ — aquí vive el código principal de la UI y las rutas MCP.

La próxima vez convertiremos ese «bosque oscuro» en un mapa comprensible.

5. Configuración de .env y OPENAI_API_KEY

Ya mencionamos antes que para la primera plantilla no es imprescindible OPENAI_API_KEY, pero se usará más adelante, así que hagámoslo desde el principio como es debido: mediante .env. La gente normal no hardcodea secretos en el código, y nosotros intentaremos ser gente normal.

Para qué sirve .env

La plantilla utiliza el archivo de entorno .env.local, desde el cual Next.js recoge las variables de entorno.

Normalmente en el repositorio o bien hay un .env.example, o bien en el README se describe qué variables hay que definir. En nuestro caso, el mínimo será OPENAI_API_KEY:

OPENAI_API_KEY=sk-tu-clave-de-OpenAI

Se recomienda usar precisamente .env.local para que los secretos locales no se mezclen con la configuración de producción.

Importa que .env.local ya esté añadido a .gitignore, es decir, Git no lo verá ni lo añadirá accidentalmente a un commit. Aun así, verifica que en .gitignore existe la línea .env*.

Dónde obtener y cómo guardar la clave de API de OpenAI

La clave de API se crea en el panel de OpenAI; suele empezar por sk-. A partir de ahí, actuamos según las reglas clásicas de higiene IT:

• no publicamos la clave en GitHub ni la enviamos por chats;
• no la pegamos en ejemplos de código en foros;
• ante sospecha de fuga — la rotamos (rotación de claves — tema de los módulos de seguridad).

En esta lección solo nos importa que la clave esté correctamente en .env.local y sea accesible mediante process.env.OPENAI_API_KEY en la parte de servidor cuando haga falta.

Matices según el sistema operativo

Hay varios detalles pequeños con los que es fácil tropezar:

• En Windows, si decides establecer variables de entorno no mediante .env, sino directamente en la línea de comandos, tendrás que usar set VAR=VALUE && comando, y no export.
• Asegúrate de que .env.local esté en la raíz del proyecto y tenga el nombre correcto: .env o .env.local, sin .txt ni otras «mejoras» del editor.

6. Primer arranque: npm run dev y localhost:3000

Ahora viene lo mejor: verificaremos que todo se haya compilado y que el proyecto arranca.

Arrancamos el servidor de desarrollo

En la raíz del proyecto ejecutamos:

npm run dev

Este comando inicia Next.js en modo desarrollo. En la terminal verás algo como:

• compilación del proyecto (usando Turbopack para un modo dev rápido);
• una línea del tipo Ready in Xs y el mensaje de que el servidor escucha el puerto 3000;
• la dirección http://localhost:3000 como URL local.

Si aparecen mensajes en rojo, no hagas scroll hacia arriba sin más, intenta leerlos: Next suele indicar bastante bien qué le falta (versión de Node, dependencias, etc.).

Abrimos en el navegador

Después, abrimos en el navegador:

http://localhost:3000

Si todo fue bien, verás la página inicial del proyecto. Entre versiones puede variar ligeramente, pero normalmente hay algún encabezado del estilo «Your ChatGPT App» o una descripción mínima del widget.

En esta etapa nos importa una sola cosa: la página se abre, no cae con un error 500 y no muestra un enorme stack trace.

Más adelante veremos que el proyecto puede diferenciar entre la «página principal» (landing) y la página del widget que realmente se incrusta en ChatGPT mediante un iframe. Por ahora, para nosotros todo el sitio es solo una forma muy cara de mostrar «Hello, world».

Imagen de lo que está ocurriendo

Para entender el panorama general, es útil ver el esquema simplificado:

+-----------------------------+
|      Tu ordenador           |
|                             |
|  +-----------------------+  |
|  |  servidor dev Next.js |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|      Navegador (Chrome)     |
+-------------+---------------+

ChatGPT y el túnel aparecerán después — por ahora te comunicas directamente con tu Next.js local mediante el navegador.

ChatGPT aquí de momento no participa en absoluto. Y eso es bueno: cuantas menos piezas en movimiento, más fácil es depurar.

7. Mini diagnóstico: qué hacer si algo sale mal

La vida demuestra que, si a alguien le funciona todo a la primera, probablemente ya se le cayó tres veces con la misma configuración. Así que veamos los problemas típicos.

Puerto 3000 ocupado

Uno de los errores más habituales: ejecutas npm run dev y Next.js se queja con algo como EADDRINUSE: address already in use 0.0.0.0:3000. Significa que el puerto 3000 ya lo está usando otro proceso.

Posibles causas:

• en otra terminal ya está corriendo npm run dev de este u otro proyecto;
• hay otro servidor en ese mismo puerto (menos frecuente, pero ocurre).

Soluciones:

• localiza y mata el proceso antiguo (a menudo basta con cerrar la otra terminal con el servidor dev);
• arranca el servidor de desarrollo en otro puerto, por ejemplo:

PORT=3001 npm run dev

En Windows, la variante sería así:

set PORT=3001 && npm run dev

No olvides entonces abrir en el navegador http://localhost:3001.

Node.js demasiado antiguo

Si tienes Node 16 o un 18 temprano, Next.js 16 puede decir claramente que esa versión no está soportada, o npm install puede fallar por incompatibilidad. La documentación de Next 16 requiere Node 20.9 o superior; mejor aún, el LTS reciente.

En ese caso, no hay alternativa: tendrás que actualizar Node. Es más rápido que intentar rodear las limitaciones de Next.js 16. Tras actualizar, a veces conviene eliminar la carpeta node_modules y el lockfile (package-lock.json) y ejecutar de nuevo npm install para que las dependencias se ajusten a la nueva versión.

Errores durante npm install

Si la instalación de dependencias falla:

• asegúrate de que tienes conexión a Internet y de que registry.npmjs.org no esté bloqueado por tu configuración local;
• comprueba la versión de Node (ver arriba);
• si cambiaste la versión de Node, puede ser útil reconstruir node_modules desde cero.

En la mayoría de los casos, el texto del error en la terminal indica en qué paquete ha fallado todo y, a menudo, dice explícitamente: «se necesita Node >= X.Y.Z».

La variable de entorno no se carga

A veces todo arranca, pero el servidor se queja de que OPENAI_API_KEY no está definida. Revisa este checklist:

• el archivo se llama .env o .env.local, está en la raíz del proyecto y Next.js lo ve;
• después de añadir/modificar .env, hay que reiniciar el servidor de desarrollo; si no, seguirá con los valores de entorno antiguos;
• la variable se llama exactamente OPENAI_API_KEY, sin faltas.

Si solo quieres ver la página del proyecto, podrías comentar temporalmente o desactivar las partes de código que requieren la clave, pero dentro del curso es mejor aprender desde ya a guardar los secretos correctamente.

Dónde ver logs y errores

Todos los errores de build y de tiempo de ejecución de Next.js en modo dev se muestran en la misma terminal donde ejecutaste npm run dev. En esta fase el código aún es escaso; los problemas típicos son dependencia ausente, .env incorrecto o Node demasiado antiguo.

También conviene abrir las DevTools del navegador (F12):

• la pestaña Console te mostrará si hay problemas en el frontend;
• Network te enseñará si algunas solicitudes a /mcp o a estáticos fallan (esto nos servirá más adelante, cuando conectemos ChatGPT).

Ahora que sabes dónde buscar errores y logs, juntemos todo en un pequeño escenario práctico.

8. Un poco de práctica: tu primera ChatGPT App ya está en marcha

Juntamos todo en un pequeño guion práctico.

1. Comprueba que node -v muestra al menos 20.9, mejor 22+.
2. Comprueba que git --version y npm -v responden algo.
3. Clona la plantilla oficial en la carpeta study-buddy-app (o como quieras llamar a tu futura App).
4. En esa carpeta ejecuta npm install.
5. Crea .env.local con OPENAI_API_KEY=....
6. Ejecuta npm run dev y abre http://localhost:3000 en el navegador.

Si todo salió bien, puedes considerar que ya tienes la ChatGPT App más simple, aunque aún no esté conectada a ChatGPT.

Para «tocar» un poco el código, puedes abrir en el editor el componente principal de React de la página (suele ser app/page.tsx) y ver algo muy parecido a este código:

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

No es necesario tocarlo todavía — en una de las próximas lecciones analizaremos con cuidado la estructura del proyecto y empezaremos a adaptarlo a nuestro escenario didáctico.

9. Errores típicos al descargar y arrancar la plantilla

Error n.º 1: usar un repositorio «random» en lugar del proyecto oficial.
A veces los estudiantes encuentran en GitHub algún «starter guay para ChatGPT» y empiezan el curso con él. El problema es que la estructura, las versiones de Next.js y del Apps SDK pueden diferir bastante del proyecto oficial en el que se basa el curso. En este curso primero dominamos el proyecto oficial y luego experimentamos con plantillas de terceros.

Error n.º 2: ignorar los requisitos de versión de Node.js.
«Me funciona todo con Node 16 desde hace tres años, ¿para qué actualizar?» — dice el desarrollador y luego se pasa una hora leyendo errores de build extraños. Next.js 16 y el Apps SDK moderno requieren un Node reciente, y no es un capricho de los autores del curso: lo dice claramente la documentación de Next.js.

Error n.º 3: comitear .env y node_modules al repositorio.
Un clásico. Si por error quitas .env o node_modules de .gitignore y lo comiteas a GitHub, en el mejor de los casos te llamarán la atención en la revisión; en el peor, se filtrará OPENAI_API_KEY. La plantilla ya está preparada para evitarlo, pero siempre es útil revisar el contenido de .gitignore y no modificarlo sin necesidad.

Error n.º 4: olvidar reiniciar el servidor de desarrollo tras cambiar .env.
Next.js lee las variables de entorno al arrancar el proceso. Si añadiste OPENAI_API_KEY a .env.local pero no reiniciaste npm run dev, el servidor seguirá con los valores antiguos y te preguntarás por qué la clave «no se ve». En la práctica, esta es una de las causas más frecuentes de confusión, así que no olvides reiniciar el servidor dev tras cambios en .env.

Error n.º 5: intentar resolver problemas de sincronización y puertos con «reinicios mágicos» del IDE.
A veces, ante un conflicto de puerto o una versión incorrecta de Node, los desarrolladores empiezan a cerrar/abrir el editor, reiniciar el ordenador, rezar, etc. El problema suele resolverse de forma mucho más prosaica: liberar el puerto 3000, actualizar Node y leer el mensaje de error en la terminal. El servidor de desarrollo dice bastante honestamente qué no le gusta; solo hay que tomarse la molestia de leerlo.