Скачиваем и разбираем ChatGPT App (Next.js 16)

1. Введение

Цель этой лекции простая, но жизненно важная: провести вас от нуля до состояния «у меня крутится рабочий ChatGPT App локально, я вижу страницу в браузере, и ничего не упало».

Мы не будем глубоко ковырять код Next.js, не будем настраивать Dev Mode в ChatGPT и не будем пока поднимать туннель — это следующие лекции модуля. Сегодня сосредотачиваемся на трёх вещах:

1. Подготовить окружение: Node.js, npm, Git, редактор, базовые проверки, чтобы Next.js 16 не умер в вашей версии Node.
2. Скачать рабочее ChatGPT App на Next.js 16: либо через git clone, либо через GitHub‑шаблон/CLI.
3. Установить зависимости, настроить .env с OPENAI_API_KEY и запустить npm run dev, убедившись, что ваш http://localhost:3000 жив и здоров.

Если к концу лекции вы увидите стартовую страницу шаблона в браузере и dev‑сервер в терминале без красных ошибок — считайте, что у вас уже есть свой рабочий ChatGPT App.

2. Минимальное окружение разработчика

Начнём с инфраструктуры. Без неё никакие модные LLM‑ы не помогут — Next.js просто не запустится.

Node.js и npm

Современный шаблон Apps SDK на Next.js 16 требует актуальный Node. Ориентируйтесь на LTS‑ветку — сейчас это, например, Node 24 LTS. Минимально приемлемая версия — 20.9, с неё Next.js 16 официально поддерживается.

Проверяем версии в терминале:

node -v
npm -v

Если вместо аккуратного v24.x.x вы видите, скажем, v16.13.0, велика вероятность, что шаблон даже не установит зависимости или Next.js будет ругаться: такая версия Node не поддерживается.

Обновиться можно «по‑простому» — через официальный установщик Node.js под вашу ОС — или, если вы уже продвинутый линуксоид/маковод, через nvm/fnm. В рамках курса мы не будем уходить в дебри менеджеров версий, главное — добиться живой LTS‑версии.

Git

Нам понадобится Git, чтобы получить шаблон и в будущем коммитить свои изменения. Проверка:

git --version

Если команда не находится, нужно установить Git (Windows‑инсталлер, Homebrew на macOS, пакетный менеджер на Linux). Для самого запуска App Git не критичен, но работать без него в 2025 году — примерно как писать на TypeScript, не зная, что такое интерфейсы.

Редактор кода

Рекомендация по умолчанию — WebStorm. Для него у JavaRush есть специальный плагин, чтобы вы могли решать задачи в пару кликов. Фактически это «де‑факто стандарт» для фронтенда и Node.

В принципе вы можете использовать VS Code, тогда желательно на него установить базовые расширения:

• поддержка TypeScript/JavaScript;
• ESLint (шаблон часто уже настроен под линтер).

Это упростит вам жизнь, когда начнём править код шаблона.

Аккаунт OpenAI / ChatGPT и API‑ключ

Для этой лекции вам достаточно иметь доступ к ChatGPT в браузере (под своим аккаунтом). Подключать Dev Mode мы будем позже, но хорошо уже сейчас убедиться, что вы можете зайти в веб‑интерфейс и там вообще есть вкладка с Developer‑функциями (Plus/Team/Enterprise в зависимости от актуальной политики OpenAI).

В будущем будет нужен OpenAI API‑ключ (OPENAI_API_KEY). Наш первый проект может подняться и без него: стартовый UI полностью статический. Но мы всё равно будем использовать ключ уже в этой лекции и положим его в .env‑файл — чуть ниже разберём, как именно это сделать и почему так безопаснее.

Ключ берётся в кабинете OpenAI, хранится как секрет, не попадает в репозиторий и вообще с ним обращаемся как с номером паспорта, только хуже.

3. Где взять рабочий ChatGPT App

Теперь — самое приятное: берём готовый стартовый проект, который уже настроен как ChatGPT App.

Почему именно этот проект

Это очень простой проект на Next.js 16, который объединяет две роли в одном репозитории: UI‑виджет и MCP‑сервер.

Структура там уже подготовлена:

• есть React‑страница, которая будет рендериться как виджет;
• есть endpoint MCP‑сервера, к которому ChatGPT будет стучаться для инструментов;
• есть готовая конфигурация Next.js (включая важные детали вроде assetPrefix для корректной загрузки ассетов в iframe ChatGPT).

Это сильно лучше, чем собирать всё с нуля.

Вариант 1: клонировать репозиторий Git

Самый прямой путь:

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

Название репозитория может немного отличаться в будущем, поэтому перед копированием команды имеет смысл свериться с актуальной ссылкой в официальной документации или комментариями под этой лекцией.

Команда git clone создаст у вас папку my-chatgpt-app с полным содержимым шаблона и уже настроенным Git‑репозиторием.

Вариант 2: кнопка «Use this template» на GitHub

Если вы хотите сразу иметь свой репозиторий в GitHub, можно:

1. Открыть страницу шаблона на GitHub.
2. Нажать кнопку «Use this template».
3. Создать на основе шаблона свой репозиторий, например username/study-buddy-chatgpt-app.
4. Потом уже клонировать именно свой репозиторий.

По сути, результат тот же: у вас локально будет папка с кодом шаблона, но Git‑remote будет указывать не на репозиторий CodeGym, а на ваш собственный.

Вариант 3: CLI‑шаблон

Скорее всего в будущем появится официальный CLI-инструмент от OpenAI, что-то вида:

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

Пока её ещё нет, так как приложения для ChatGPT только начали развиваться. Но вполне может быть, что к моменту, когда вы читаете данную лекцию, что-то такое уже появилось. Такую команду обязательно нужно поискать в официальной документацией Apps SDK.

Логика та же: CLI просто скачивает и разворачивает тот же самый или очень похожий шаблон. Такое было для создания плагинов для ChatGPT, поэтому спустя какое-то время, думаю, обязательно появится и для приложения.

4. Установка зависимостей и первый взгляд на проект

Предположим, у вас уже есть папка my-chatgpt-app с рабочим проектом. Пора поставить зависимости.

npm install

Переходим в папку проекта и ставим зависимости:

cd my-chatgpt-app
npm install

Скрипт прочитает package.json, в котором уже прописаны необходимые пакеты: Next.js, React, Tailwind, Apps SDK и MCP SDK (@modelcontextprotocol/sdk).

В результате появится каталог node_modules — тот самый монстр на сотни мегабайт, который мы никогда не коммитим в Git. Он обычно уже добавлен в .gitignore в шаблоне, так что дополнительно ничего настраивать не нужно.

Если в процессе установки зависимостей что‑то падает, не паникуем: разбор типичных проблем будет чуть ниже.

Мини‑осмотр содержимого

Сейчас не нужно углубляться в структуру папок — это тема следующей лекции, где мы детально разберём, что где лежит. Но полезно хотя бы заглянуть в корень проекта:

• package.json — список зависимостей и скриптов.
• next.config.ts — конфиг Next.js с дополнительными настройками для работы внутри ChatGPT.
• tsconfig.json — конфигурация TypeScript.
• app/ — здесь живёт основной код UI и MCP‑роуты.

В следующий раз мы превратим этот «тёмный лес» в понятную карту.

5. Настройка .env и OPENAI_API_KEY

Раньше мы уже упоминали, что для первого шаблона не нужен OPENAI_API_KEY, но он будет использоваться в будущем, поэтому давайте сразу всё сделаем по‑взрослому: через .env. Нормальные люди секреты в код не хардкодят — мы с вами тоже постараемся быть нормальными.

Зачем нужен .env

В шаблоне используется файл окружения .env.local, откуда Next.js подхватывает переменные окружения.

Обычно в репозитории либо лежит .env.example, либо в README описано, какие переменные нужно задать. В нашем случае минимумом будет OPENAI_API_KEY:

OPENAI_API_KEY=sk-ваш-ключ-от-OpenAI

Рекомендуют использовать именно .env.local, чтобы локальные секреты не путались с настройками продакшена.

Важно, что .env.local уже добавлен в .gitignore, то есть Git его не увидит и случайно не добавит в коммит. Всё равно лишний раз проверьте, что в .gitignore действительно есть строка .env*.

Где брать и как хранить OpenAI API‑ключ

API‑ключ создаётся в панели OpenAI; он начинается обычно с sk-. Дальше действуем по классическим правилам ИТ‑гигиены:

• ключ не публикуем в GitHub и не отправляем в чаты;
• не вставляем в примеры кода на форумах;
• при подозрении на утечку — меняем (ротация ключей — тема модулей по безопасности).

В этой лекции нам важно только, чтобы ключ корректно лежал в .env.local и был доступен через process.env.OPENAI_API_KEY в серверной части, когда она понадобится.

Нюансы для разных ОС

Есть несколько мелких нюансов, на которые легко наступить:

• На Windows, если вы вдруг решите задавать переменные окружения не через .env, а напрямую в командной строке, придётся использовать set VAR=VALUE && команда, а не export.
• Следите, чтобы .env.local был в корне проекта и имел правильное имя: .env или .env.local, без .txt и прочих «улучшений» от редактора.

6. Первый запуск: npm run dev и localhost:3000

Теперь самое приятное: проверим, что всё собралось и проект запускается.

Запускаем dev‑сервер

В корне проекта выполняем:

npm run dev

Эта команда запускает Next.js в режиме разработки. В терминале вы увидите примерно следующее:

• сборка проекта (с использованием Turbopack для быстрого dev‑режима);
• строку вида Ready in Xs и сообщение о том, что сервер слушает порт 3000;
• адрес http://localhost:3000 как локальный URL.

Если появляются красные сообщения об ошибках — не скрольте их сразу вверх, а попытайтесь прочитать: Next довольно неплохо подсказывает, чего ему не хватает (версии Node, зависимостей и т.п.).

Открываем в браузере

Дальше открываем в браузере:

http://localhost:3000

Если всё прошло успешно, вы увидите стартовую страницу проекта. В разных версиях она может выглядеть чуть по‑разному, но обычно там есть какой‑то заголовок наподобие «Your ChatGPT App» или минимальное описание виджета.

На этом этапе нам важно только одно: страница открывается, не падает с 500‑й ошибкой и не показывает гигантский стектрейс.

Позже мы увидим, что у проекта может быть различие между «главной страницей» (landing) и страницей виджета, которая реально встраивается в ChatGPT через iframe. Но пока для нас весь сайт — просто очень дорогой способ показать «Hello, world».

Картинка происходящего

Для понимания общей картины полезно посмотреть на упрощённую схему:

+-----------------------------+
|      Ваш компьютер          |
|                             |
|  +-----------------------+  |
|  |  dev-сервер Next.js   |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|      Браузер (Chrome)       |
+-------------+---------------+

ChatGPT и туннель появятся позже — пока вы общаетесь напрямую с локальным Next.js через браузер.

ChatGPT здесь пока не участвует вообще. И это хорошо: меньше движущихся частей — легче отлаживать.

7. Мини‑диагностика: что делать, если что‑то пошло не так

Жизнь показывает: если у кого‑то всё поднялось с первого раза — он, скорее всего, уже три раза до этого падал на той же конфигурации. Поэтому разбираем типовые проблемы.

Порт 3000 занят

Одна из самых частых ошибок: вы запускаете npm run dev, а Next.js ругается на что‑то вроде EADDRINUSE: address already in use 0.0.0.0:3000. Это значит, что порт 3000 уже занят другим процессом.

Возможные причины:

• где‑то в другом терминале уже крутится npm run dev из этого или другого проекта;
• на этом же порту работает какой‑то другой сервер (реже, но бывает).

Решения:

• найти и убить старый процесс (часто достаточно закрыть другой терминал с dev‑сервером);
• запустить dev‑сервер на другом порту, например:

PORT=3001 npm run dev

На Windows вариант будет выглядеть так:

set PORT=3001 && npm run dev

Не забывайте тогда открывать в браузере http://localhost:3001.

Слишком старый Node.js

Если у вас стоит Node 16 или ранний 18, Next.js 16 может честно сказать, что такой Node не поддерживается, или npm install упадёт с ошибкой несовместимости. Документация Next 16 требует Node не ниже 20.9, а лучше сразу свежий LTS.

В этом случае вариантов нет: придётся обновить Node. Это быстрее, чем пытаться обойти ограничения Next.js 16. После обновления иногда полезно удалить папку node_modules и lock‑файл (package-lock.json) и заново выполнить npm install, чтобы зависимости подтянулись под новую версию.

Ошибки при npm install

Если установка зависимостей падает:

• убедитесь, что интернет работает и registry.npmjs.org не заблокирован локальными настройками;
• проверьте версию Node (см. выше);
• при смене версии Node имеет смысл пересобрать node_modules с нуля.

В большинстве случаев текст ошибки в терминале подсказывает, на каком пакете всё развалилось, и часто прямо пишет: «нужен Node >= X.Y.Z».

Переменная окружения не подхватывается

Бывает, что всё запускается, но сервер жалуется, что OPENAI_API_KEY не задан. Здесь проверяем по чек‑листу ниже:

• файл называется .env или .env.local, лежит в корне проекта и Next.js его видит;
• после добавления/изменения .env dev‑сервер нужно перезапустить, иначе он так и будет жить со старыми значениями окружения;
• переменная названа точно OPENAI_API_KEY, без опечаток.

Если вы просто хотите увидеть страницу проекта, можно временно закомментировать или отключить куски кода, которые требуют ключ, но в рамках курса лучше сразу научиться хранить секреты правильно.

Где смотреть логи и ошибки

Все ошибки сборки и runtime‑ошибки Next.js в dev‑режиме выводятся в тот же терминал, где вы запустили npm run dev. На этом этапе кода ещё немного, поэтому типичные проблемы — пропущенная зависимость, неправильный .env или слишком старый Node.

Также стоит открыть DevTools в браузере (F12):

• вкладка Console подскажет, если что‑то не так с фронтендом;
• Network покажет, если какие‑то запросы к /mcp или статике падают (это нам пригодится позже, когда будем подключать ChatGPT).

Теперь, когда вы знаете, где искать ошибки и логи, давайте соберём всё вместе в виде короткого практического сценария.

8. Небольшая практика: ваш первый ChatGPT App уже запущен

Соберём всё вместе в виде небольшого практического сценария.

1. Проверяете, что node -v показывает хотя бы 20.9, а лучше 22+.
2. Проверяете, что git --version и npm -v вообще что‑то отвечают.
3. Клонируете официальный шаблон в папку study-buddy-app (или как хотите назвать свой будущий App).
4. В этой папке запускаете npm install.
5. Создаёте .env.local с OPENAI_API_KEY=....
6. Запускаете npm run dev и открываете http://localhost:3000 в браузере.

Если всё получилось — можно считать, что у вас уже есть самый простой ChatGPT App, пусть пока и не подключённый к ChatGPT.

Чтобы немного «осязать» код, вы можете открыть в редакторе главный React‑компонент страницы (обычно это app/page.tsx) и увидеть там что‑то очень похожее на такой код:

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

Трогать его пока не обязательно — в одной из следующих лекций мы аккуратно разберём структуру проекта и начнём его адаптировать под наш учебный сценарий.

9. Типичные ошибки при скачивании и запуске шаблона

Ошибка №1: использовать «левый» репозиторий вместо официального проекта.
Иногда студенты находят на GitHub какой‑нибудь «крутой стартер для ChatGPT» и начинают курс с него. Проблема в том, что структура, версии Next.js и Apps SDK там могут сильно отличаться от официального проекта, на который опирается курс. В рамках этого курса мы сначала осваиваем именно официальный проект, а уже потом экспериментируем с чужими шаблонами.

Ошибка №2: игнорировать требования к версии Node.js.
«У меня же всё работает на Node 16 уже три года, зачем обновляться?» — говорит разработчик и потом час читает странные ошибки сборки. Next.js 16 и современный Apps SDK требуют свежий Node, и это не прихоть авторов курса: об этом прямо говорится в документации Next.js.

Ошибка №3: коммитить .env и node_modules в репозиторий.
Это классика. Если вы по ошибке уберёте .env или node_modules из .gitignore и закоммитите всё это на GitHub, в лучшем случае вас будут стыдить в ревью, в худшем — утечёт OPENAI_API_KEY. Шаблон уже настроен так, чтобы этого не происходило, но всегда полезно проверить содержимое .gitignore и не править его без необходимости.

Ошибка №4: забыть перезапустить dev‑сервер после изменения .env.
Next.js читает переменные окружения при старте процесса. Если вы добавили OPENAI_API_KEY в .env.local, но не перезапустили npm run dev, сервер продолжит жить со старыми пустыми значениями, а вы будете удивляться, почему ключ «не виден». На практике это одна из самых частых причин путаницы, поэтому не забывайте перезапускать dev‑сервер после правок в .env.

Ошибка №5: пытаться решить проблемы синхронизации и портов «магическими» перезапусками IDE.
Иногда при конфликте порта или неправильной версии Node разработчики начинают закрывать/открывать редактор, перезагружать компьютер, молиться и т.д. Проблема при этом обычно решается гораздо более прозаично: освободить порт 3000, обновить Node и перечитать текст ошибки в терминале. Dev‑сервер довольно честно пишет, что ему не нравится, — нужно просто не лениться это прочитать.