Pobieramy i rozkładamy na czynniki pierwsze ChatGPT App (Next.js 16)

1. Wprowadzenie

Celem tej lekcji jest proste, ale bardzo ważne zadanie: przeprowadzić cię od zera do stanu „lokalnie działa mi ChatGPT App, widzę stronę w przeglądarce i nic się nie wywaliło”.

Nie będziemy głęboko grzebać w kodzie Next.js, nie będziemy konfigurować Dev Mode w ChatGPT ani na razie stawiać tunelu — to kolejne lekcje modułu. Dziś skupiamy się na trzech rzeczach:

1. Przygotować środowisko: Node.js, npm, Git, edytor, podstawowe sprawdzenia, aby Next.js 16 nie wywrócił się na twojej wersji Node.
2. Pobrać działający ChatGPT App na Next.js 16: albo przez git clone, albo przez szablon GitHub/CLI.
3. Zainstalować zależności, skonfigurować .env z OPENAI_API_KEY i uruchomić npm run dev, upewniając się, że twój http://localhost:3000 żyje i ma się dobrze.

Jeśli pod koniec lekcji zobaczysz w przeglądarce stronę startową szablonu, a serwer dev w terminalu będzie działał bez czerwonych błędów — uznaj, że masz już swój działający ChatGPT App.

2. Minimalne środowisko deweloperskie

Zaczniemy od infrastruktury. Bez niej żadne modne LLM-y nie pomogą — Next.js po prostu się nie uruchomi.

Node.js i npm

Współczesny szablon Apps SDK na Next.js 16 wymaga aktualnego Node. Trzymaj się gałęzi LTS — obecnie to na przykład Node 24 LTS. Minimalnie akceptowalna wersja to 20.9, od niej Next.js 16 jest oficjalnie wspierany.

Sprawdzamy wersje w terminalu:

node -v
npm -v

Jeśli zamiast zgrabnego v24.x.x widzisz na przykład v16.13.0, jest duża szansa, że szablon nawet nie zainstaluje zależności albo Next.js będzie narzekał: taka wersja Node nie jest wspierana.

Zaktualizować można „po prostu” — przez oficjalny instalator Node.js dla twojego systemu — albo, jeśli jesteś bardziej zaawansowanym użytkownikiem Linuksa/macOS, przez nvm/fnm. W ramach kursu nie będziemy schodzić w szczegóły menedżerów wersji, najważniejsze — mieć działającą wersję LTS.

Git

Będzie nam potrzebny Git, aby pobrać szablon i w przyszłości commitować własne zmiany. Sprawdzenie:

git --version

Jeśli polecenie nie jest znalezione, trzeba zainstalować Git (instalator Windows, Homebrew na macOS, menedżer pakietów na Linuksie). Do samego uruchomienia aplikacji Git nie jest krytyczny, ale pracować bez niego w 2025 roku to jak pisać w TypeScript, nie wiedząc, czym są interfejsy.

Edytor kodu

Domyślna rekomendacja — WebStorm. JavaRush ma do niego specjalną wtyczkę, dzięki której możesz rozwiązywać zadania kilkoma kliknięciami. W praktyce to „de facto standard” dla frontendu i Node.

Możesz oczywiście używać VS Code, wtedy warto doinstalować podstawowe rozszerzenia:

• obsługa TypeScript/JavaScript;
• ESLint (szablon często jest już skonfigurowany pod linter).

To ułatwi ci życie, gdy zaczniemy modyfikować kod szablonu.

Konto OpenAI/ChatGPT i klucz API

Na tę lekcję wystarczy, że masz dostęp do ChatGPT w przeglądarce (na swoim koncie). Dev Mode podłączymy później, ale dobrze już teraz upewnić się, że możesz wejść do interfejsu web i w ogóle masz tam zakładkę z funkcjami developerskimi (Plus/Team/Enterprise zależnie od aktualnej polityki OpenAI).

W przyszłości będzie potrzebny klucz OpenAI API (OPENAI_API_KEY). Nasz pierwszy projekt może wstać i bez niego: startowy UI jest w pełni statyczny. Mimo to użyjemy klucza już w tej lekcji i włożymy go do pliku .env — niżej omówimy, jak to zrobić i dlaczego tak jest bezpieczniej.

Klucz pobieramy w panelu OpenAI, przechowujemy jako sekret, nie trafia do repozytorium i w ogóle traktujemy go jak numer paszportu, tylko jeszcze ostrożniej.

3. Skąd wziąć działający ChatGPT App

Teraz — najprzyjemniejsze: bierzemy gotowy projekt startowy, który jest już skonfigurowany jako ChatGPT App.

Dlaczego właśnie ten projekt

To bardzo prosty projekt na Next.js 16, który łączy dwie role w jednym repozytorium: widżet UI i serwer MCP.

Struktura jest już przygotowana:

• jest strona React, która będzie renderowana jako widżet;
• jest endpoint serwera MCP, do którego ChatGPT będzie się odzywać dla narzędzi;
• jest gotowa konfiguracja Next.js (w tym ważne detale jak assetPrefix dla poprawnego ładowania assetów w iframe ChatGPT).

To zdecydowanie lepsze, niż składać wszystko od zera.

Wariant 1: sklonować repozytorium Git

Najprostsza droga:

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

Nazwa repozytorium może się w przyszłości nieco różnić, więc przed skopiowaniem komendy warto zerknąć na aktualny link w oficjalnej dokumentacji albo w komentarzach pod tą lekcją.

Polecenie git clone utworzy u ciebie folder my-chatgpt-app z pełną zawartością szablonu i już skonfigurowanym repozytorium Git.

Wariant 2: przycisk „Use this template” na GitHub

Jeśli chcesz od razu mieć własne repozytorium na GitHub, możesz:

1. Otworzyć stronę szablonu na GitHub.
2. Kliknąć przycisk „Use this template”.
3. Utworzyć na podstawie szablonu własne repozytorium, np. username/study-buddy-chatgpt-app.
4. Potem sklonować już swoje repozytorium.

W istocie rezultat jest ten sam: lokalnie będziesz mieć folder z kodem szablonu, ale Git remote będzie wskazywać nie na repozytorium CodeGym, tylko na twoje własne.

Wariant 3: szablon CLI

Najprawdopodobniej w przyszłości pojawi się oficjalne narzędzie CLI od OpenAI, coś w stylu:

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

Na razie jeszcze go nie ma, ponieważ aplikacje dla ChatGPT dopiero zaczęły się rozwijać. Ale całkiem możliwe, że w momencie, gdy czytasz tę lekcję, coś takiego już istnieje. Takiej komendy warto poszukać w oficjalnej dokumentacji Apps SDK.

Logika jest ta sama: CLI po prostu pobiera i rozpakowuje ten sam lub bardzo podobny szablon. Tak było przy tworzeniu wtyczek do ChatGPT, więc po jakimś czasie zapewne pojawi się też dla aplikacji.

4. Instalacja zależności i pierwsze spojrzenie na projekt

Załóżmy, że masz już folder my-chatgpt-app z działającym projektem. Czas zainstalować zależności.

npm install

Przechodzimy do folderu projektu i instalujemy zależności:

cd my-chatgpt-app
npm install

Skrypt odczyta package.json, w którym są już wpisane potrzebne pakiety: Next.js, React, Tailwind, Apps SDK i MCP SDK (@modelcontextprotocol/sdk).

W efekcie pojawi się katalog node_modules — ten potwór o setkach megabajtów, którego nigdy nie commitujemy do Git. Zwykle jest już dodany do .gitignore w szablonie, więc nie trzeba nic dodatkowo ustawiać.

Jeśli podczas instalacji zależności coś się wywraca, bez paniki: typowe problemy omówimy nieco niżej.

Mini‑przegląd zawartości

Teraz nie trzeba zagłębiać się w strukturę folderów — to temat następnej lekcji, gdzie szczegółowo rozbierzemy, co gdzie leży. Warto jednak rzucić okiem w katalog główny projektu:

• package.json — lista zależności i skryptów.
• next.config.ts — konfiguracja Next.js z dodatkowymi ustawieniami do pracy wewnątrz ChatGPT.
• tsconfig.json — konfiguracja TypeScript.
• app/ — tutaj żyje główny kod UI i trasy MCP.

Następnym razem zamienimy ten „ciemny las” w zrozumiałą mapę.

5. Konfiguracja .env i OPENAI_API_KEY

Wspomnieliśmy wcześniej, że dla pierwszego szablonu nie jest potrzebny OPENAI_API_KEY, ale będzie używany w przyszłości, więc zróbmy od razu wszystko „po dorosłemu”: przez .env. Normalni ludzie nie hardcodują sekretów w kodzie — my też postaramy się być normalni.

Po co jest .env

W szablonie używany jest plik środowiskowy .env.local, z którego Next.js pobiera zmienne środowiskowe.

Zwykle w repozytorium leży .env.example albo w README opisano, jakie zmienne trzeba ustawić. W naszym przypadku minimum to OPENAI_API_KEY:

OPENAI_API_KEY=sk-twoj-klucz-do-OpenAI

Rekomenduje się używać właśnie .env.local, aby lokalne sekrety nie mieszały się z ustawieniami produkcyjnymi.

Ważne, że .env.local jest już dodany do .gitignore, czyli Git go nie zobaczy i przypadkowo nie doda do commita. Mimo to warto jeszcze raz sprawdzić, że w .gitignore faktycznie znajduje się linia .env*.

Skąd brać i jak przechowywać klucz OpenAI API

Klucz API tworzy się w panelu OpenAI; zwykle zaczyna się od sk-. Dalej stosujemy klasyczne zasady higieny IT:

• nie publikujemy klucza w GitHubie ani nie wysyłamy go na czatach;
• nie wklejamy go do przykładów kodu na forach;
• przy podejrzeniu wycieku — zmieniamy (rotacja kluczy to temat modułów o bezpieczeństwie).

W tej lekcji ważne jest tylko to, aby klucz poprawnie leżał w .env.local i był dostępny przez process.env.OPENAI_API_KEY po stronie serwera, kiedy będzie potrzebny.

Niuanse dla różnych systemów operacyjnych

Jest kilka drobnych niuansów, o które łatwo się potknąć:

• Na Windows, jeśli postanowisz ustawiać zmienne środowiskowe nie przez .env, lecz bezpośrednio w wierszu poleceń, trzeba użyć set VAR=VALUE && komenda, a nie export.
• Pilnuj, by .env.local był w katalogu głównym projektu i miał poprawną nazwę: .env albo .env.local, bez .txt i innych „ulepszeń” edytora.

6. Pierwsze uruchomienie: npm run dev i localhost:3000

Teraz najprzyjemniejsze: sprawdzimy, że wszystko się zbudowało i projekt się uruchamia.

Uruchamiamy serwer deweloperski

W katalogu głównym projektu wykonujemy:

npm run dev

To polecenie uruchamia Next.js w trybie deweloperskim. W terminalu zobaczysz mniej więcej:

• budowanie projektu (z wykorzystaniem Turbopack dla szybkiego trybu dev);
• linię w stylu Ready in Xs i informację, że serwer nasłuchuje na porcie 3000;
• adres http://localhost:3000 jako lokalny URL.

Jeśli pojawiają się czerwone komunikaty o błędach — nie przewijaj od razu do góry, tylko spróbuj je przeczytać: Next całkiem nieźle podpowiada, czego mu brakuje (wersji Node, zależności itp.).

Otwieramy w przeglądarce

Dalej otwieramy w przeglądarce:

http://localhost:3000

Jeśli wszystko poszło pomyślnie, zobaczysz stronę startową projektu. W różnych wersjach może wyglądać trochę inaczej, ale zwykle jest tam jakiś nagłówek w rodzaju „Your ChatGPT App” albo minimalny opis widżetu.

Na tym etapie ważne jest tylko jedno: strona się otwiera, nie sypie błędem 500 i nie pokazuje gigantycznego stack trace’a.

Później zobaczymy, że projekt może mieć różnicę między „stroną główną” (landing) a stroną widżetu, która faktycznie jest osadzana w ChatGPT przez iframe. Na razie jednak cały serwis to po prostu bardzo drogi sposób na pokazanie „Hello, world”.

Obraz sytuacji

Żeby lepiej zrozumieć ogólny obraz, warto spojrzeć na uproszczony schemat:

+-----------------------------+
|      Twój komputer          |
|                             |
|  +-----------------------+  |
|  |  serwer dev Next.js   |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|  Przeglądarka (Chrome)      |
+-------------+---------------+

ChatGPT i tunel pojawią się później — na razie łączysz się bezpośrednio z lokalnym Next.js przez przeglądarkę.

ChatGPT na tym etapie w ogóle nie uczestniczy. I dobrze: mniej ruchomych elementów — łatwiej debugować.

7. Mini‑diagnostyka: co zrobić, gdy coś poszło nie tak

Życie pokazuje: jeśli komuś wszystko podniosło się za pierwszym razem — to najpewniej już trzy razy wcześniej wywracał się na tej samej konfiguracji. Dlatego omawiamy typowe problemy.

Port 3000 jest zajęty

Jeden z najczęstszych błędów: uruchamiasz npm run dev, a Next.js zgłasza coś w stylu EADDRINUSE: address already in use 0.0.0.0:3000. To znaczy, że port 3000 jest już zajęty przez inny proces.

Możliwe przyczyny:

• gdzieś w innym terminalu już działa npm run dev z tego lub innego projektu;
• na tym porcie działa jakiś inny serwer (rzadziej, ale bywa).

Rozwiązania:

• znaleźć i ubić stary proces (często wystarczy zamknąć drugi terminal z serwerem dev);
• uruchomić serwer dev na innym porcie, na przykład:

PORT=3001 npm run dev

Na Windows wariant będzie wyglądał tak:

set PORT=3001 && npm run dev

Nie zapomnij wtedy otwierać w przeglądarce http://localhost:3001.

Zbyt stary Node.js

Jeśli masz Node 16 albo wczesne 18, Next.js 16 może uczciwie powiedzieć, że taki Node nie jest wspierany, albo npm install wywali się błędem niezgodności. Dokumentacja Next 16 wymaga Node co najmniej 20.9, a najlepiej od razu świeże LTS.

W takim wypadku nie ma wyjścia: trzeba zaktualizować Node. To szybciej, niż próbować obchodzić ograniczenia Next.js 16. Po aktualizacji czasem warto usunąć katalog node_modules i plik lock (package-lock.json) i ponownie wykonać npm install, aby zależności dopasowały się do nowej wersji.

Błędy przy npm install

Jeśli instalacja zależności się sypie:

• upewnij się, że masz działający internet i registry.npmjs.org nie jest blokowany lokalnymi ustawieniami;
• sprawdź wersję Node (zob. wyżej);
• po zmianie wersji Node warto przebudować node_modules od zera.

W większości przypadków treść błędu w terminalu podpowiada, na którym pakiecie wszystko się rozpadło, i często wprost pisze: „wymagany Node >= X.Y.Z”.

Zmienna środowiskowa nie jest wczytywana

Zdarza się, że wszystko się uruchamia, ale serwer narzeka, że OPENAI_API_KEY nie jest ustawiony. Sprawdź wtedy listę kontrolną poniżej:

• plik nazywa się .env lub .env.local, leży w katalogu głównym projektu i Next.js go widzi;
• po dodaniu/zmianie .env trzeba zrestartować serwer dev, inaczej będzie żył ze starymi wartościami środowiska;
• zmienna nazywa się dokładnie OPENAI_API_KEY, bez literówek.

Jeśli po prostu chcesz zobaczyć stronę projektu, możesz tymczasowo zakomentować lub wyłączyć fragmenty kodu, które wymagają klucza, ale w ramach kursu lepiej od razu nauczyć się przechowywać sekrety poprawnie.

Gdzie oglądać logi i błędy

Wszystkie błędy budowania i błędy runtime Next.js w trybie dev są wypisywane w ten sam terminal, w którym uruchomiłeś npm run dev. Na tym etapie kodu jest jeszcze niewiele, więc typowe problemy to: brakująca zależność, nieprawidłowy .env albo zbyt stary Node.

Warto też otworzyć DevTools w przeglądarce (F12):

• zakładka Console podpowie, jeśli coś jest nie tak po stronie frontendu;
• Network pokaże, jeśli jakieś żądania do /mcp lub statyki się wywracają (przyda się później, gdy będziemy podłączać ChatGPT).

Teraz, gdy wiesz, gdzie szukać błędów i logów, złóżmy wszystko w krótki scenariusz praktyczny.

8. Mała praktyka: twój pierwszy ChatGPT App już działa

Zbierzmy wszystko w postaci krótkiego scenariusza praktycznego.

1. Sprawdzasz, że node -v pokazuje co najmniej 20.9, a najlepiej 22+.
2. Sprawdzasz, że git --version i npm -v w ogóle coś odpowiadają.
3. Klonujesz oficjalny szablon do folderu study-buddy-app (albo jak chcesz nazwać swój przyszły App).
4. W tym folderze uruchamiasz npm install.
5. Tworzysz .env.local z OPENAI_API_KEY=....
6. Uruchamiasz npm run dev i otwierasz http://localhost:3000 w przeglądarce.

Jeśli wszystko się udało — możesz uznać, że masz już najprostszy ChatGPT App, choć jeszcze nie podłączony do ChatGPT.

Aby trochę „poczuć” kod, możesz w edytorze otworzyć główny komponent Reacta strony (zwykle to app/page.tsx) i zobaczyć coś bardzo podobnego do takiego kodu:

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

Na razie nie musisz tego dotykać — w jednej z kolejnych lekcji spokojnie rozbierzemy strukturę projektu i zaczniemy ją dostosowywać do naszego scenariusza szkoleniowego.

9. Typowe błędy przy pobieraniu i uruchamianiu szablonu

Błąd nr 1: użyć „lewnego” repozytorium zamiast oficjalnego projektu.
Czasem studenci znajdują na GitHubie jakiś „super starter dla ChatGPT” i zaczynają kurs od niego. Problem w tym, że struktura, wersje Next.js i Apps SDK mogą się tam mocno różnić od oficjalnego projektu, na którym opiera się kurs. W ramach tego kursu najpierw opanowujemy oficjalny projekt, a dopiero potem eksperymentujemy z cudzymi szablonami.

Błąd nr 2: ignorować wymagania co do wersji Node.js.
„Przecież wszystko działa mi na Node 16 od trzech lat, po co aktualizować?” — mówi deweloper, a potem godzinę czyta dziwne błędy budowania. Next.js 16 i nowoczesny Apps SDK wymagają świeżego Node i to nie jest kaprys autorów kursu: jest o tym wprost w dokumentacji Next.js.

Błąd nr 3: commitować .env i node_modules do repozytorium.
Klasyka. Jeśli przez pomyłkę usuniesz .env albo node_modules z .gitignore i wrzucisz to wszystko na GitHuba, w najlepszym razie dostaniesz burę w review, w najgorszym — wycieknie OPENAI_API_KEY. Szablon jest już ustawiony tak, by do tego nie doszło, ale zawsze warto sprawdzić zawartość .gitignore i nie zmieniać jej bez potrzeby.

Błąd nr 4: zapomnieć zrestartować serwer dev po zmianie .env.
Next.js czyta zmienne środowiskowe przy starcie procesu. Jeśli dodałeś OPENAI_API_KEY do .env.local, ale nie zrestartowałeś npm run dev, serwer będzie dalej żył ze starymi pustymi wartościami, a ty będziesz się dziwić, czemu klucz „nie jest widoczny”. W praktyce to jedna z najczęstszych przyczyn zamieszania, więc pamiętaj o restarcie serwera dev po zmianach w .env.

Błąd nr 5: próbować rozwiązać problemy z synchronizacją i portami „magicznymi” restartami IDE.
Czasem przy konflikcie portu albo nieprawidłowej wersji Node deweloperzy zaczynają zamykać/otwierać edytor, restartować komputer, modlić się itd. Problem zwykle rozwiązuje się dużo prościej: zwolnić port 3000, zaktualizować Node i przeczytać treść błędu w terminalu. Serwer dev dość uczciwie pisze, co mu nie pasuje — trzeba tylko nie lenić się, by to przeczytać.