ChatGPT App-i yükləyirik və incələyirik (Next.js 16)

1. Giriş

Bu mühazirənin məqsədi sadə, amma həyati əhəmiyyətlidir: sizi sıfırdan “məndə yerli mühitdə işlək ChatGPT App işləyir, səhifəni brauzerdə görürəm və heç nə çökməyib” vəziyyətinə gətirmək.

Biz Next.js kodunu dərindən qurdalamayacağıq, ChatGPT-də Dev Mode qurmadan və hələ tunnel qaldırmadan keçəcəyik — bunlar modulun növbəti mühazirələridir. Bu gün üç məsələyə fokuslanırıq:

1. Mühiti hazırlamaq: Node.js, npm, Git, redaktor, baza yoxlamaları — Next.js 16 sizin Node versiyanızda “ölməsin” deyə.
2. Next.js 16 üzərində işlək ChatGPT App endirmək: ya git clone ilə, ya da GitHub‑şablonu/CLI vasitəsilə.
3. Asılılıqları quraşdırmaq, .env faylını OPENAI_API_KEY ilə tənzimləmək və npm run dev işə salmaq; http://localhost:3000 ünvanının “sağ‑salamat” işlədiyinə əmin olmaq.

Mühazirənin sonunda brauzerdə şablonun başlanğıc səhifəsini görüb terminalda dev‑server qırmızı xətalarsız işləyirsə — deməli, artıq öz işlək ChatGPT App‑iniz var.

2. Minimum inkişaf mühiti

İnfrastrukturdan başlayaq. Onsuz heç bir dəbli LLM kömək etməyəcək — Next.js sadəcə işə düşməyəcək.

Node.js və npm

Next.js 16 üzərində müasir Apps SDK şablonu aktual Node tələb edir. LTS qoluna yönəlin — hazırda, məsələn, Node 24 LTS. Minimal qəbul olunan versiya — 20.9; bu versiyadan etibarən Next.js 16 rəsmi şəkildə dəstəklənir.

Versiyaları terminalda yoxlayırıq:

node -v
npm -v

Əgər səliqəli v24.x.x əvəzinə, məsələn, v16.13.0 görürsünüzsə, böyük ehtimalla şablon asılılıqları belə qurulmayacaq və ya Next.js narazılıq edəcək: bu cür Node versiyası dəstəklənmir.

Yeniləmə “sadə yolla” — OS‑iniz üçün rəsmi Node.js quraşdırıcısı ilə — edilə bilər və ya artıq irəli səviyyəli Linux/macOS istifadəçisisinizsə, nvm/fnm vasitəsilə. Kurs çərçivəsində versiya menecerlərinin dərinliyinə getməyəcəyik; əsas olan işlək LTS versiyasına çatmaqdır.

Git

Şablonu əldə etmək və gələcəkdə öz dəyişikliklərinizi commit etmək üçün Git lazım olacaq. Yoxlama:

git --version

Əgər komanda tapılmırsa, Git quraşdırmaq lazımdır (Windows quraşdırıcısı, macOS‑da Homebrew, Linux‑da paket meneceri). Tətbiqin sırf işə düşməsi üçün Git kritik deyil, amma 2025‑ci ildə onsuz işləmək — sanki TypeScript yazıb interfeysin nə olduğunu bilməmək kimidir.

Kod redaktoru

Defolt tövsiyə — WebStorm. JavaRush üçün xüsusi plaqin var ki, tapşırıqları bir neçə kliklə həll edə biləsiniz. Faktiki olaraq bu, frontend və Node üçün “de‑fakto standart”dır.

Prinsipcə VS Code istifadə edə bilərsiniz, o halda aşağıdakı əsas genişlənmələri quraşdırmaq məqsədəuyğundur:

• TypeScript/JavaScript dəstəyi;
• ESLint (şablon çox vaxt artıq linter üçün qurulub).

Şablon kodunu redaktə etməyə başlayanda bu, işinizi xeyli asanlaşdıracaq.

OpenAI / ChatGPT hesabı və API açarı

Bu mühazirə üçün brauzerdə (öz hesabınızla) ChatGPT‑yə çıxışınızın olması kifayətdir. Dev Mode‑u sonra qoşacağıq, amma elə indi veb‑interfeysə daxil ola bildiyinizi və orada ümumiyyətlə Developer funksiyaları bölməsinin (Plus/Team/Enterprise — OpenAI‑nin aktual siyasətindən asılı olaraq) olduğunu yoxlamaq yaxşıdır.

Gələcəkdə OpenAI API açarı (OPENAI_API_KEY) lazım olacaq. İlk layihəmiz onsuz da qalxa bilər: start UI tam statikdir. Yenə də bu mühazirədə açardan istifadə edəcəyik və onu .env faylına yerləşdirəcəyik — bir azdan bunu necə və niyə daha təhlükəsiz etdiyimizi izah edəcəyik.

Açar OpenAI kabinetində yaradılır, gizli saxlanılır, repozitoriyaya düşmür və onunla pasport nömrəsindən də ehtiyatla rəftar edirik.

3. İşlək ChatGPT App-ı haradan götürmək olar

İndi — ən xoş hissə: ChatGPT App kimi artıq tənzimlənmiş hazır başlanğıc layihəni götürürük.

Məhz niyə bu layihə

Bu, Next.js 16 üzərində çox sadə bir layihədir; bir repozitoriyada iki rolu birləşdirir: UI vidceti və MCP serverini.

Struktur artıq hazırdır:

• vidcet kimi render olunacaq React səhifəsi var;
• alətlər üçün ChatGPT‑nin müraciət edəcəyi MCP server endpoint‑i var;
• ChatGPT iframe‑ində assetlərin düzgün yüklənməsi üçün assetPrefix kimi vacib detallar daxil olmaqla hazır Next.js konfiqurasiyası var.

Bu, hər şeyi sıfırdan toplamaqdan qat‑qat yaxşıdır.

Variant 1: Git repozitoriyasını klonlamaq

Ən birbaşa yol:

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

Repozitoriyanın adı gələcəkdə bir qədər fərqlənə bilər, ona görə komandaları kopyalamazdan əvvəl rəsmi sənədlərdə və ya bu mühazirənin şərhlərində aktual linki dəqiqləşdirmək məntiqlidir.

git clone komandası sizdə my-chatgpt-app adlı qovluq yaradacaq; şablonun bütün məzmunu və artıq qurulmuş Git repozitoriyası orada olacaq.

Variant 2: GitHub‑da “Use this template” düyməsi

Əgər dərhal GitHub‑da öz repozitoriyanızın olmasını istəyirsinizsə, aşağıdakıları edin:

1. GitHub‑da şablonun səhifəsini açın.
2. “Use this template” düyməsini sıxın.
3. Şablon əsasında öz repozitoriyanızı yaradın, məsələn, username/study-buddy-chatgpt-app.
4. Sonra məhz öz repozitoriyanızı klonlayın.

Əslində nəticə eynidir: sizdə lokalda şablon kodu olan qovluq olacaq, sadəcə Git‑remote CodeGym repozitoriyasına yox, sizin öz repozitoriyanıza işarə edəcək.

Variant 3: CLI şablonu

Böyük ehtimalla gələcəkdə OpenAI‑dan rəsmi CLI aləti çıxacaq, təxminən belə:

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

Hələ ki belə bir alət yoxdur, çünki ChatGPT üçün tətbiqlər yalnız inkişaf etməyə başlayıb. Amma siz bu mühazirəni oxuyanda artıq nəsə yaranmış ola bilər. Belə komandanı mütləq Apps SDK‑nın rəsmi sənədlərində axtarın.

Məntiq eynidir: CLI sadəcə həmin və ya çox oxşar şablonu endirib açır. ChatGPT üçün plagin yaratmaqda belə idi, ona görə bir müddət sonra tətbiq üçün də mütləq görünəcək.

4. Asılılıqların qurulması və layihəyə ilk baxış

Tutaq ki, sizdə artıq my-chatgpt-app adlı işçi layihə qovluğu var. Vaxtdır asılılıqları quraq.

npm install

Layihə qovluğuna keçib asılılıqları quraşdırırıq:

cd my-chatgpt-app
npm install

Skript package.json faylını oxuyacaq; burada artıq tələb olunan paketlər yazılıb: Next.js, React, Tailwind, Apps SDK və MCP SDK (@modelcontextprotocol/sdk).

Nəticədə node_modules kataloqu yaranacaq — yüzlərlə meqabaytlıq “canavar”, heç vaxt Git‑ə commit etmirik. Adətən şablonda o artıq .gitignore‑a əlavə olunub, əlavə tənzimləməyə ehtiyac yoxdur.

Asılılıqların quraşdırılması zamanı nəsə çökərsə, panikaya ehtiyac yoxdur: tipik problemləri bir azdan nəzərdən keçirəcəyik.

Mini-baxış: məzmun

İndi qovluq strukturuna dərindən girməyə ehtiyac yoxdur — bu, növbəti mühazirənin mövzusudur; orada nəyin harada olduğunu detallı araşdıracağıq. Amma ən azı layihənin kökünə göz atmaq faydalıdır:

• package.json — asılılıqlar və skriptlərin siyahısı.
• next.config.ts — ChatGPT daxilində işləmək üçün əlavə tənzimləmələri olan Next.js konfiqi.
• tsconfig.json — TypeScript konfiqurasiyası.
• app/ — əsas UI kodu və MCP routelar burada yaşayır.

Növbəti dəfə bu “qaranlıq meşə”ni anlaşılan xəritəyə çevirəcəyik.

5. .env və OPENAI_API_KEY quraşdırılması

Əvvəllər demişdik ki, ilk şablon üçün OPENAI_API_KEY vacib deyil, lakin gələcəkdə istifadə olunacaq, ona görə gəlin hər şeyi dərhal düzgün edək: .env vasitəsilə. Normal insanlar sirləri koda hardcode etmir — biz də normal davranmağa çalışacağıq.

Niyə .env lazımdır

Şablonda .env.local faylı istifadə olunur; Next.js mühit dəyişənlərini buradan götürür.

Adətən repozitoriyada ya .env.example olur, ya da README‑də hansı dəyişənləri vermək lazım olduğu yazılır. Bizim halda minimum OPENAI_API_KEY olacaq:

OPENAI_API_KEY=sk-sizin-OpenAI-acariniz

Məhz .env.local istifadə etmək tövsiyə olunur ki, lokal sirlər prod konfiqlərlə qarışmasın.

Vacibdir ki, .env.local artıq .gitignore‑a əlavə olunub, yəni Git onu görməyəcək və təsadüfən commita salmayacaq. Yenə də .gitignore daxilində həqiqətən .env* sətrinin olduğunu bir daha yoxlayın.

OpenAI API açarını haradan almaq və necə saxlamaq

API açarı OpenAI panelində yaradılır; adətən sk- ilə başlayır. Sonra klassik İT gigiyenasına əməl edirik:

• açarı GitHub‑da yayımlamırıq və çatlarda göndərmirik;
• forumlarda kod nümunələrinə yerləşdirmirik;
• sızma şübhəsi yaranarsa — dəyişirik (açarların rotasiyası — təhlükəsizlik modullarının mövzusudur).

Bu mühazirədə vacib olan odur ki, açar düzgün şəkildə .env.local daxilində saxlanılsın və server tərəfində lazım olanda process.env.OPENAI_API_KEY vasitəsilə əlçatan olsun.

Müxtəlif OS‑lər üçün incəliklər

Bəzi xırda nüanslar var ki, asanlıqla “tələyə” çevrilə bilər:

• Windows‑da əgər mühit dəyişənlərini .env vasitəsilə yox, birbaşa komanda sətrindən vermək istəsəniz, set VAR=VALUE && komanda istifadə etməli olacaqsınız, export yox.
• .env.local layihənin kökündə olsun və adı düzgün yazılsın: .env və ya .env.local, .txt və s. “redaktor yaxşılaşdırmaları” olmadan.

6. İlk işə salma: npm run dev və localhost:3000

İndi ən xoş hissə: hər şeyin yığıldığını və layihənin işə düşdüyünü yoxlayaq.

Dev‑serveri işə salırıq

Layihənin kökündə icra edirik:

npm run dev

Bu komanda Next.js‑i inkişaf rejimində işə salır. Terminalda təxminən belə məlumat görəcəksiniz:

• layihənin yığılması (sürətli dev rejimi üçün Turbopack istifadə olunur);
• Ready in Xs sətri və serverin 3000 portunu dinlədiyini bildirən mesaj;
• lokal URL kimi http://localhost:3000 ünvanı.

Əgər qırmızı səhv mesajları çıxırsa — dərhal yuxarıya skrol etməyin, oxumağa çalışın: Next adətən nəyin çatmadığını (Node versiyası, asılılıqlar və s.) kifayət qədər aydın göstərir.

Brauzerdə açırıq

Sonra brauzerdə açırıq:

http://localhost:3000

Hər şey uğurludursa, layihənin başlanğıc səhifəsini görəcəksiniz. Müxtəlif versiyalarda o bir qədər fərqli görünə bilər, amma adətən orada “Your ChatGPT App” tipli başlıq və ya vidcet haqqında minimal təsvir olur.

Bu mərhələdə bizə yalnız bir şey vacibdir: səhifə açılır, 500 səhvi ilə çökmür və nəhəng stack trace göstərmir.

Daha sonra görəcəyik ki, layihədə “əsas səhifə” (landing) ilə həqiqətən ChatGPT‑yə iframe vasitəsilə yerləşdirilən vidcet səhifəsi arasında fərq ola bilər. Amma hələlik bütün sayt bizim üçün “Hello, world” göstərməyin çox bahalı yoludur.

Görünən mənzərə

Ümumi mənzərəni anlamaq üçün sadələşdirilmiş sxemə baxmaq faydalıdır:

+-----------------------------+
|     Sizin kompüteriniz      |
|                             |
|  +-----------------------+  |
|  |   Next.js dev-serveri |  |
|  |   (npm run dev)       |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|       Brauzer (Chrome)      |
+-------------+---------------+

ChatGPT və tunel sonra görünəcək — hələlik siz brauzer vasitəsilə lokal Next.js ilə birbaşa ünsiyyətdəsiniz.

Burada ChatGPT ümumiyyətlə iştirak etmir. Bu isə yaxşıdır: hərəkət edən hissələr azdır — sazlama asandır.

7. Mini‑diaqnostika: nəsə səhv gedərsə nə etməli

Təcrübə göstərir: kimdəsə hər şey ilk cəhddə qalxıbsa — böyük ehtimalla o, eyni konfiqurasiyada artıq üç dəfə yıxılıb‑qalxıb. Ona görə tipik problemləri nəzərdən keçirək.

3000 portu məşğuldur

Ən çox rast gəlinən səhvlərdən biri: siz npm run dev işə salırsınız, Next.js isə təxminən EADDRINUSE: address already in use 0.0.0.0:3000 kimi xəbərdarlıq edir. Bu, 3000 portunun başqa proses tərəfindən tutulduğu anlamına gəlir.

Mümkün səbəblər:

• başqa terminalda bu və ya başqa layihədən npm run dev artıq işləyir;
• həmin portda başqa server işləyir (daha nadir, amma mümkündür).

Həllər:

• köhnə prosesi tapıb dayandırın (çox vaxt digər dev‑server olan terminalı bağlamaq kifayətdir);
• dev‑serveri başqa portda işə salın, məsələn:

PORT=3001 npm run dev

Windows üçün variant belə olacaq:

set PORT=3001 && npm run dev

Onda brauzerdə http://localhost:3001 açmağı unutmayın.

Həddindən artıq köhnə Node.js

Əgər sizdə Node 16 və ya erkən 18 varsa, Next.js 16 bu cür Node‑un dəstəklənmədiyini açıqca deyə bilər və ya npm install uyğunsuzluq xətası ilə çökə bilər. Next 16 sənədləri Node 20.9‑dan aşağı olmayan versiya tələb edir; ən yaxşısı isə dərhal aktual LTS‑dir.

Bu halda seçim yoxdur: Node‑u yeniləmək lazımdır. Next.js 16 məhdudiyyətlərini dolaşmağa çalışmaqdan daha sürətlidir. Yeniləmədən sonra bəzən node_modules qovluğunu və lock‑faylı (package-lock.json) silib npm install‑ı yenidən icra etmək faydalıdır ki, asılılıqlar yeni versiyaya uyğun qurulsun.

npm install zamanı xətalar

Əgər asılılıqların qurulması çökürsə:

• internetin işlədiyini və registry.npmjs.org ünvanının lokal ayarlarınızda bloklanmadığını yoxlayın;
• Node versiyasını yoxlayın (yuxarıya baxın);
• Node versiyasını dəyişəndə node_modules‑i sıfırdan yenidən qurmaq məqsədəuyğundur.

Çox vaxt terminaldakı səhv mətni hər şeyin hansı paketdə dağıldığını göstərir və bəzən birbaşa belə yazır: “Node >= X.Y.Z lazımdır”.

Mühit dəyişəni götürülmür

Bəzən hər şey işə düşür, amma server OPENAI_API_KEY‑in təyin olunmadığından şikayət edir. Burada aşağıdakı yoxlama siyahısını keçiririk:

• faylın adı .env və ya .env.local‑dır, layihənin kökündədir və Next.js onu görür;
• .env faylına əlavə/dəyişiklikdən sonra dev‑serveri yenidən başlatmaq lazımdır, əks halda o, köhnə mühit dəyərləri ilə işləməyə davam edəcək;
• dəyişənin adı dəqiq OPENAI_API_KEY‑dir, səhvsiz.

Sadəcə layihə səhifəsini görmək istəyirsinizsə, müvəqqəti olaraq açar tələb edən kod hissələrini şərhə sala və ya söndürə bilərsiniz, amma kurs çərçivəsində sirləri dərhal düzgün saxlamağı öyrənməyimiz daha yaxşıdır.

Logları və xətaları harada görmək olar

Yığım xətaları və Next.js‑in runtime xətaları dev rejimində elə npm run dev işə saldığınız terminalda göstərilir. Bu mərhələdə kod da azdır, ona görə tipik problemlər — çatışmayan asılılıq, səhv .env və ya çox köhnə Node‑dur.

Həmçinin brauzerdə DevTools (F12) açmağa dəyər:

• Console sekmesi frontend‑də nəsə qaydasında deyilsə xəbər verəcək;
• Network /mcp və ya statik fayllara olan sorğuların yıxılıb‑yıxılmadığını göstərəcək (bu bizə sonra, ChatGPT‑ni qoşanda lazım olacaq).

Artıq xətaları və logları harada axtaracağınızı bildiyinizə görə, gəlin hər şeyi qısa praktik ssenaridə birləşdirək.

8. Kiçik praktika: ilk ChatGPT App‑iniz artıq işə düşüb

Gəlin hər şeyi qısa praktik ssenari şəklində toplayaq.

1. node -v ən azı 20.9 göstərdiyinə, daha yaxşısı 22+ olduğuna əmin olun.
2. git --version və npm -v komandalarının cavab verdiyini yoxlayın.
3. Rəsmi şablonu study-buddy-app qovluğuna (və ya gələcək App‑inizi necə adlandırmaq istəyirsinizsə) klonlayın.
4. Bu qovluqda npm install işə salın.
5. .env.local yaradın və OPENAI_API_KEY=... əlavə edin.
6. npm run dev işə salın və brauzerdə http://localhost:3000 açın.

Hər şey alınıbsa — demək, sizdə artıq ən sadə ChatGPT App var, hələ ki, ChatGPT‑yə qoşulmasa da.

Kodu bir az “hiss etmək” üçün redaktorda səhifənin əsas React komponentini (adətən app/page.tsx) açıb təxminən bu cür kodu görə bilərsiniz:

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

Hələlik ona toxunmaq vacib deyil — növbəti mühazirələrdən birində layihənin strukturunu səliqə ilə araşdıracaq və onu tədris ssenarimizə uyğunlaşdırmağa başlayacağıq.

9. Şablonu endirib işə salarkən tipik səhvlər

Səhv №1: rəsmi layihə əvəzinə “sol” repozitoriyadan istifadə etmək.
Bəzən tələbələr GitHub‑da hansısa “super ChatGPT starter” tapıb kursa onunla başlayırlar. Problem ondadır ki, oradakı struktur, Next.js və Apps SDK versiyaları kursun əsaslandığı rəsmi layihədən ciddi fərqlənə bilər. Bu kurs çərçivəsində əvvəlcə məhz rəsmi layihəni mənimsəyirik, sonra isə yad şablonlarla eksperimenti edirik.

Səhv №2: Node.js versiyası tələblərini görməzlikdən gəlmək.
“Axı məndə hər şey Node 16‑da üç ildir işləyir, niyə yeniləyim?” — deyir developer və sonra saatlarla qəribə yığım xətalarını oxuyur. Next.js 16 və müasir Apps SDK daha yeni Node tələb edir; bu, kurs müəlliflərinin kaprizi deyil: bu barədə Next.js sənədlərində birbaşa deyilir.

Səhv №3: .env və node_modules qovluqlarını repozitoriyaya commit etmək.
Bu klassikadır. Əgər səhvən .env və ya node_modules‑i .gitignore‑dan çıxarıb hamısını GitHub‑a commit etsəniz, ən yaxşı halda review‑da tənqid olunacaqsınız, ən pisi — OPENAI_API_KEY sızacaq. Şablon artıq bunun baş verməməsi üçün qurulub, amma yenə də .gitignore məzmununu yoxlamaq və ehtiyac olmadan dəyişməmək faydalıdır.

Səhv №4: .env dəyişəndən sonra dev‑serveri yenidən başlatmağı unutmaq.
Next.js mühit dəyişənlərini prosesin startında oxuyur. Əgər OPENAI_API_KEY‑i .env.local‑a əlavə etdiniz, amma npm run dev‑i yenidən başlatmadınızsa, server köhnə boş dəyərlərlə işləməyə davam edəcək, siz isə açarın “görünməməyinə” təəccüblənəcəksiniz. Praktikada bu, ən geniş yayılmış qarışıqlıqlardandır, ona görə .env faylında düzəlişdən sonra dev‑serveri yenidən başladın.

Səhv №5: sinxronizasiya və port problemlərini IDE‑ni “Sehrli” şəkildə yenidən açıb‑bağlamaqla həll etməyə çalışmaq.
Bəzən port konflikti və ya səhv Node versiyası zamanı developerlər redaktoru bağlayıb‑açır, kompüteri yenidən başladır, dua edir və s. Problem isə adətən daha sadə həll olunur: 3000 portunu boşaltmaq, Node‑u yeniləmək və terminaldakı səhv mətnini oxumaq. Dev‑server nəyin xoşuna gəlmədiyini kifayət qədər dürüst yazır — sadəcə bunu oxumağa ərinməmək lazımdır.