Лекції
Почати
Почати навчання
JavaRush /Курси /ChatGPT Apps /Завантажуємо й розбираємо ChatGPT App (Next.js 16)

Завантажуємо й розбираємо ChatGPT App (Next.js 16)

ChatGPT Apps
Рівень 2 , Лекція 0
Відкрита

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 для вашої ОС. Або ж (якщо ви користуєтеся Linux чи macOS) — через nvm/fnm. У межах курсу ми не заглиблюватимемося в менеджери версій: головне — отримати робочу LTS‑версію.

Git

Нам знадобиться Git, щоб отримати шаблон, а в майбутньому — комітити свої зміни. Перевірка: 

git --version

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

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

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

Загалом ви можете користуватися VS Code. Тоді бажано встановити базові розширення:

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

Це помітно спростить роботу, коли ми почнемо редагувати код шаблону.

Обліковий запис OpenAI / ChatGPT і API‑ключ

Для цієї лекції вам достатньо мати доступ до ChatGPT у браузері (під своїм обліковим записом). Dev Mode ми підʼєднаємо пізніше, але вже зараз варто переконатися, що ви можете зайти у вебінтерфейс і що там узагалі є вкладка з функціями для розробників (Plus/Team/Enterprise — залежно від актуальної політики OpenAI).

У майбутньому знадобиться OpenAI API‑ключ (OPENAI_API_KEY). Наш перший проєкт може запуститися і без нього: стартовий UI повністю статичний. Але ми все одно використаємо ключ уже в цій лекції та збережемо його у файлі .env — трохи нижче розберемо, як саме це зробити й чому так безпечніше.

Ключ береться в кабінеті OpenAI, зберігається як секрет, не потрапляє в репозиторій — і загалом із ним варто поводитися дуже обережно.

Вебінар JavaRush

3. Де взяти робочий ChatGPT App

Тепер — найприємніше: беремо готовий стартовий проєкт, який уже налаштовано як ChatGPT App.

Чому саме цей проєкт

Це дуже простий проєкт на Next.js 16, який поєднує дві ролі в одному репозиторії: UI‑віджет і MCP‑сервер.

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

  • є React‑сторінка, яка рендериться як віджет;
  • є ендпойнт 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.js досить добре підказує, чого саме бракує (версії 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 може чесно повідомити, що така версія не підтримується. Або ж 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 (або як вам зручно назвати свій майбутній застосунок).
  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>Лише дві дії: отримати дані з <code>/api/time</code> і відкрити зовнішнє посилання.</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‑сервер доволі прямо пише, що саме йому не подобається, — важливо лише не лінуватися це прочитати.

Коментарі
ЩОБ ПОДИВИТИСЯ ВСІ КОМЕНТАРІ АБО ЗАЛИШИТИ КОМЕНТАР,
ПЕРЕЙДІТЬ В ПОВНУ ВЕРСІЮ