Vercel-ə deploy: repozitoriya, env dəyişənləri, preview → production

1. Niyə ChatGPT Tətbiqi üçün Vercel

Ötən dərslərdə GiftGenius-i lokalda işə salıb onu ChatGPT-yə Dev Mode və tunel vasitəsilə qoşmuşduq. İndi “böyüklər” prodakşeninə daha bir addım atmağın və eyni kodu Vercel-ə köçürməyin vaxtıdır.

Bu məqamda sizdə artıq işlək GiftGenius tətbiqi var (şərti tədris App-ımız). Lokalda o, Next.js 16-da MCP endpoint ilə (məsələn, /api/mcp) işləyir və rəsmi ChatGPT Apps SDK Next.js Starter-ə əsaslanır.

Teorik olaraq “VPS icarəyə götürürəm, Node-u, nginx-i əllə quraşdırıb hər şeyi özüm tənzimləyirəm” yolu ilə getmək olardı, amma Next.js üçün bu, 2025-ci ildə frontend-i təmiz document.write ilə yazmaq kimidir. İşləyir, amma özünüzə həyatı xeyli çətinləşdirirsiniz.

Vercel bizim üçün bir neçə səbəbə görə uyğundur.

Birincisi, o, Next.js-i təbii şəkildə “anlayır”: build-i, SSR-i, statikanı, edge qatını və serverless funksiyaları avtomatik qurur. ChatGPT Tətbiqi üçün bu xüsusilə rahatdır, çünki vidcet və MCP endpoint bir düymə ilə yayımlanır və eyni infrastrukturda yaşayır.

İkincisi, Vercel CI/CD-ni hazır şəkildə verir: Git repozitoriyasını qoşursunuz — və hər push unikal URL-ə malik yeni, dəyişməz (immutable) deployment yaradır. main budağından olanlar production sayılır, digər budaqlardan — preview.

Üçüncüsü, Vercel-in mühitlər və sirlərlə bağlı xoş hekayəsi var. O, env dəyişənlərini açıq şəkildə Development, Preview və Production olaraq ayırır, şifrəli saxlayır və onları Next.js-ə rahat ötürməyə imkan verir. Bu, məhz ChatGPT Tətbiqi üçün gərəkli olan şeydir: açarlar və MCP serverinin URL-i mühitdən asılı olaraq dəyişməlidir.

Dördüncüsü, Vercel-də rahat rollback-lər var: yeni reliz uğursuz olarsa, əvvəlki uğurlu deploy-u tez bir zamanda production-a “promote” edib sistemi işlək vəziyyətə qaytarmaq olar. Bu, “deploy qorxusu”nu azaldır və kiçik, tez-tez buraxılışları təşviq edir.

Və nəhayət, Vercel — Next.js-in yaradıcısı olan şirkətdir. Onlar Next.js-i öz serverlərinə, serverlərini də Next.js-ə uyğunlaşdırıblar. Vercel-dən istifadə edərkən dəfələrlə hiss edəcəksiniz ki, hər şey bir neçə kliklə və çox hamar işləyir. Zəmanət verirəm, xoşunuza gələcək.

2. İlkin nöqtə: GiftGenius layihəsinin strukturu

Kurs planımıza görə GiftGenius tək repozitoriyada yaşayır. Təşkilatın iki variantı var və hər ikisi Vercel üçün uyğundur:

1) Bir neçə tətbiqi olan monorepo — məsələn:

giftgenius/
  apps/
    web/   # Next.js (vidcet + MCP)
    mcp/   # ayrı MCP serveri (əgər siz onu ayırmısınızsa)

2) Tək bir Next.js layihəsi, burada həm vidcet, həm də MCP bir yerdə yaşayır (ilk mərhələdə daha sadədir və rəsmi starter də məhz belə qurulub):

giftgenius/
  app/
    page.tsx         # Vidcet
    api/
      mcp/route.ts   # MCP endpoint
  next.config.mjs
  package.json
  ...

Modul 2 dərslərində siz artıq Apps SDK Starter-i klonlamısınız, asılılıqları quraşdırmısınız və npm run dev işə salmısınız. İndi güman edirik ki:

• layihə artıq Git-dədir (GitHub / GitLab / Bitbucket);
• lokalda siz .env.local-dan açarlarla (OPENAI_API_KEY və s.) istifadə edirsiniz;
• ChatGPT Dev Mode tunelinizə qoşulub.

Məqsədimiz — eyni kodun Vercel-də yığılması və işləməsi, həm də ChatGPT-nin tunelə yox, https://giftgenius.vercel.app kimi sabit HTTPS domeninə müraciət etməsidir.

3. Deploy üçün repozitoriyanın hazırlanması

Vercel-də “New Project” düyməsini basmazdan əvvəl, repozitoriyanı bir az səliqəyə salmağa dəyər. Bunlar sadə addımlardır, amma sonradan çox vaxt qazandırır.

Birincisi, .env.local və .vercel fayllarının repozitoriyaya düşmədiyindən əmin olun. .gitignore-da Next.js Starter üçün bu adətən artıq var, amma yenə də yoxlamaq yaxşıdır:

node_modules
.next
.env.local
.vercel

.env.local — sizin lokal konfiqiniz və sirlərinizdir. O, heç vaxt Git-ə düşməməlidir, xüsusən də içində OPENAI_API_KEY və ya verilənlər bazası açarları varsa. Vercel-də sirləri ayrıca UI-da saxlayacağıq.

İkincisi, package.json-a baxın. Vercel üçün düzgün scripts vacibdir:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Vercel standart olaraq npm run build (və ya pnpm istifadə edirsinizsə, pnpm build) çağıracaq. Bu, layihəni xətasız yığmalıdır.

Üçüncüsü, Node versiyasının göstərildiyinə və Next.js 16 üçün uyğun olduğuna əmin olun. Next.js 16 buraxılış qeydlərində minimal versiya — 18.18.0-dır. Çox vaxt package.json-da bu sahə kifayətdir:

{
  "engines": {
    "node": ">=18.18.0"
  }
}

Vercel tətbiqinizlə uyğun olan Node-un LTS versiyasını seçəcək.

H bunların hamısı edilibsə, son kodu Git-ə push edib Vercel-ə keçə bilərsiniz.

4. Layihənin Vercel-ə ilk importu

İndi Vercel-in veb interfeysinə keçirik. Hələ orada qeydiyyatdan keçməmisinizsə — vaxtıdır.

Vercel-ə daxil olursunuz, “New Project” düyməsini basırsınız və siyahıdan öz giftgenius repozitoriyanızı seçirsiniz. Bu mərhələdə Vercel pərdə arxasında repozitoriyanın məzmununu yoxlayır və demək olar ki, həmişə bunun Next.js layihəsi olduğunu özü müəyyənləşdirərək uyğun preset təyin edir.

Layihə ayarlarında Vercel aşağıdakıları təklif edəcək:

• Framework = Next.js;
• Build Command = npm run build (və ya pnpm build/yarn build);
• Output Directory — standart .next (dəyişməyə ehtiyac yoxdur).

İlk deploy üçün env dəyişənlərini dərhal göstərməyə də bilərsiniz (onları ayrıca addımda əlavə edəcəyik). “Deploy” düyməsini basırsınız — Vercel repozitoriyanı klonlayır, asılılıqları quraşdırır, npm run build işlədir və hər şey uğurludursa, https://giftgenius-xyz.vercel.app kimi ünvana malik ilk deploy yaradır.

Bir şeyi anlamaq vacibdir: hər bir deploy — dəyişməzdir (immutable). Sonra dəyişiklikləri push etsəniz, yeni URL ilə yeni deploy yaradılacaq, köhnəsi isə tarixçədə qalacaq. Prodakşen domeni (məsələn, giftgenius.vercel.app və ya sizin öz domeniniz) konkret deploy-a işarə edir və rollback edərək onu geri çevirmək olar.

Sxematik olaraq bu belə görünür:

flowchart LR
    A[GitHub repo
giftgenius] -->|git push| B[Vercel build]
    B --> C[Preview deploy #1
unikal URL]
    B --> D[Preview deploy #2
unikal URL]
    D --> E[Production alias
giftgenius.vercel.app]

Git budağı main adətən production budağı sayılır, qalanları — preview. Amma bunu yenidən tənzimləmək olar.

5. Vercel-də mühit dəyişənləri (env)

Hazırda ilk deploy-unuz, yəqin ki, tam işlək deyil: OPENAI_API_KEY yoxdur, MCP serveri xarici API-lərə çıxmır və s. İndi env dəyişənlərinə baxmağın vaxtıdır.

Vercel-də env dəyişənləri Settings → Environment Variables bölməsində saxlanılır. Orada həmçinin üç scope-a bölünmə görünür: Development, Preview və Production.

Mental model üçün kiçik cədvəl:

Lokal .env.local-dan fərqli olaraq, Vercel dəyərləri şifrəli saxlayır və onları Next.js kodunda process.env.MY_VAR kimi avtomatik təqdim edir.

NEXT_PUBLIC_ prefiksini anlamaq çox vacibdir. NEXT_PUBLIC_ ilə başlayan hər şey brauzer bundl-una düşəcək və istənilən istifadəçiyə görünəcək (DevTools-da görmək olar). Bu, publik konfiqurasiya üçün yaxşıdır (NEXT_PUBLIC_ENV=preview, NEXT_PUBLIC_API_BASE_URL=https://giftgenius.vercel.app), amma OPENAI_API_KEY kimi açarlar üçün qətiyyən olmaz.

Sirlər üçün prefikssiz adlardan istifadə edirik və onları yalnız server tərəfində oxuyuruq: route handler-lərdə, MCP alətlərində və s.

6. GiftGenius üçün env sazlaması: nümunə

Gəlin tədris tətbiqimiz GiftGenius üçün hansı env dəyişənlərinin lazım olduğuna baxaq.

Minimal dəst bu cür ola bilər:

• OPENAI_API_KEY — modelləri/MCP müştərisini çağırmaq üçün açar;
• APP_BASE_URL — tətbiqin baza URL-i (https://giftgenius.vercel.app və ya preview URL);
• mümkün GIFTDATA_API_URL və ya PRODUCTS_API_URL, əgər xarici kataloqunuz varsa.

Lokal inkişafda bunlar .env.local-da olur:

OPENAI_API_KEY=sk-local-...
APP_BASE_URL=http://localhost:3000
PRODUCTS_API_URL=https://dev-api.gifts.example.com

Vercel-də Settings → Environment Variables bölməsinə gedib eyni açarları və dəyərləri uyğun scope-larda əlavə edirsiniz.

MCP endpoint kodunda bunun necə göründüyünə misal:

// app/api/mcp/route.ts
import { NextRequest } from 'next/server';

const apiKey = process.env.OPENAI_API_KEY!; // real kodda yoxlamalarsız bunu etməyin :)

export async function POST(req: NextRequest) {
  if (!apiKey) {
    return new Response('Missing OPENAI_API_KEY', { status: 500 });
  }
  // OpenAI və ya başqa xidmətə apiKey ilə çağırış...
}

V idcet server tərəfində APP_BASE_URL-dən istifadə edə bilər, məsələn, ChatGPT iframe-ni və assetPrefix/basePath konfiqurasiyasını nəzərə alaraq mütləq linklər qurmaq üçün.

Əgər ona publik API URL lazımdırsa (məsələn, backend-ə window.fetch üçün), bunun üçün NEXT_PUBLIC_API_BASE_URL yarada bilərsiniz. Amma əsla NEXT_PUBLIC_OPENAI_API_KEY yox.

7. Preview deploy-lar: gücləndirilmiş staging

İndi ən xoş hissə — preview deploy-lar. Git repozitoriyasını qoşduğunuz anda Vercel production olmayan budaqlara hər push (və ya hər Pull Request) üçün avtomatik preview deploy yaradır. Hər belə deploy-un unikal URL-i olur, məsələn:

https://giftgenius-git-feature-new-layout-username.vercel.app

Bu deploy-lar env dəyişənləri üçün Preview scope-dan istifadə edir, buna görə məsələn, belə təyin edə bilərsiniz:

# Vercel-də Preview env
APP_BASE_URL=https://giftgenius-staging.vercel.app
PRODUCTS_API_URL=https://staging-api.gifts.example.com

və bunu production ilə qarışdırmayın.

ChatGPT Dev Mode baxımından preview URL — staging üçün ideal namizəddir. Dev App ayarlarında endpoint-i müvəqqəti olaraq tunel URL-indən preview URL-ə dəyişib artıq yığılmış, amma hələ production olmayan GiftGenius versiyasının necə davrandığını yoxlaya bilərsiniz.

Tez-tez istifadə olunan fənd: funksiya üçün feature/smart-recommendations budağı yaradırsınız, dəyişiklikləri push edirsiniz — Vercel preview link verir. Dev Mode-a gedib URL-i bu linkə dəyişirsiniz, GPT ilə ssenariləri yoxlayırsınız (hədiyyə seçimi, kartların göstərilməsi, MCP alətlərinin çağırılması). Hər şey qaydasındadırsa, main-ə merge edirsiniz. Production isə hələ sakit həyatına davam edir.

Pipeline-in mental sxemi:

flowchart TD
    A[Local dev
localhost + tunel] --> B[git push
feature/*]
    B --> C[Preview deploy
preview URL]
    C --> D[ChatGPT Dev Mode
App → preview URL]
    C --> E[Code review / testlər]
    E --> F[main-ə merge]
    F --> G[Production deploy
prod URL]
    G --> H[ChatGPT Prod App
App → prod URL]

8. Production deploy və rollback

Dəyişiklikləri main (və ya sizin seçdiyiniz başqa production budağı) ilə birləşdirəndə, Vercel production deploy yaradır və ona production alias bağlayır: giftgenius.vercel.app və ya öz domeniniz.

Bu anda ChatGPT Prod App (bir az sonra yaradacaqsınız) production URL-ə yönləndirilməlidir. Dev Mode-da isə siz tunel və ya preview URL ilə eksperimentləri davam etdirəcəksiniz; ChatGPT Store-dakı adi istifadəçilər məhz production-a gedəcəklər.

Dəyişməz deploy-ların üstünlüyü ondadır ki, rollback çox sadə olur. Yeni reliz uğursuz alınsa (məsələn, MCP aləti “dövüş” verilənlərində yıxılırsa), prod-da təcili düzəliş etməyə ehtiyac yoxdur. Vercel-də deploy siyahısını açırsınız, əvvəlki uğurlu olanı seçirsiniz və “Promote to Production” kimi bir şeyə basırsınız — haradasa uzaqda K8s və Lambda yenidən bağlanır və domeniniz yenidən stabil versiyaya işarə edir.

CLI vasitəsilə də bunu vercel rollback komandaları ilə avtomatlaşdıra bilərsiniz, amma kurs səviyyəsində ideyanı başa düşmək kifayətdir: hər deploy — ayrıca artefaktdır, production alias isə onların istənilən birinə yönləndirilə bilər.

9. Vercel-də Next.js 16 + MCP-nin özəllikləri

Vercel baxımından sizin MCP endpoint-iniz Next.js-də serverless funksiya (və ya belə konfiqurasiya etmisinizsə, edge funksiya) kimi işləyir. O, qısaömürlüdür: sorğu gələndə “oyanır”, onu emal edir və “ölür”. Çağırışlar arasında vəziyyəti saxlamaq olmaz, yalnız xarici DB və ya hər hansı saxlama istifadə etmirsinizsə.

Bu, MCP üçün kritikdir: əgər birdən dialoq tarixçəsini let history = [] adlı qlobal massivdə route.ts-də saxlamağa qərar versəniz, o, hər “soyuq start”da sıfırlanacaq. Vəziyyəti saxlamaq üçün (KV, Postgres və s.) xarici sistem lazımdır, amma bu, gələcək modulların mövzusudur.

İkinci məqam — icra müddəti üçün timeout-lar. Pulsuz planlarda Vercel serverless funksiyalarının vaxt məhdudiyyəti var (materialların hazırlandığı anda — 10 saniyə civarında Hobby planında, Pro-da daha çox). LLM sorğuları, xüsusən də MCP alətləri zəncirləri üçün bu az ola bilər.

Next.js 16-da route handler-lər üçün maxDuration təyin etmək olar ki, Vercel-dən daha çox vaxt istəsin (plan çərçivəsində):

// app/api/mcp/route.ts
export const maxDuration = 60; // saniyə, Pro-da 300-ə qədər

export async function POST(req: Request) {
  // uzunmüddətli əməliyyat: OpenAI sorğusu, xarici DB və s.
}

Bu, “istədiyin qədər et” sehrli düyməsi deyil, amma Vercel-ə düzgün mesajdır: “bu funksiya bir az daha uzun işləyə bilər, xahiş edirik, onu tez öldürməyin”.

Nəhayət, ChatGPT iframe-inin özəlliklərini unutmayın. Apps SDK Starter-də assetPrefix və basePath artıq elə qurulub ki, statika və marşrutlar web-sandbox.oaiusercontent.com daxilindəki nested iframe-lərdə düz işləsin. Bunun sayəsində bütün sorğular sandbox-a yox, domeninizə gedir. Vercel-ə deploy edəndə bu konfiqurasiya saxlanılır və vidcet qutudan çıxan kimi düzgün işləyir.

10. Deploydan sonra ChatGPT ilə inteqrasiya

Formal olaraq bu, Store və production modullarına daha yaxındır, amma deploydan sonrakı tətbiq həyatı və ChatGPT ilə inteqrasiya məntiqi kifayət qədər sadədir və artıq indi “yatır”.

Əvvəlcə GiftGenius-i Vercel-ə deploy edirsiniz və production URL alırsınız. Sonra ChatGPT-də Dev Mode-da ayrıca bir Tətbiq yaradırsınız, məsələn, GiftGenius Prod, və onun ayarlarında endpoint kimi bu URL-i göstərirsiniz (daha dəqiqi, OpenAI Apps SDK Deploy bələdçisinə uyğun olaraq https://giftgenius.vercel.app/api/mcp kimi MCP endpoint).

İnkişaf üçün Dev App-dan istifadə etməyə davam edirsiniz, o, tunelə və ya preview URL-ə baxır. Gündəlik/həftəlik build-ləri test etmək üçün sabit preview alias-a bağlanan ayrıca Staging App da yarada bilərsiniz. Nəticədə üçpilləli sxem alınır:

Dev App     → lokal tunel və ya dev URL (stabil deyil)
Staging App → Vercel-də sabit preview/staging URL
Prod App    → Vercel-də production URL

İstinad üçün hamısını bir cədvəldə toplayaq:

Bu, modulun əvvəlində danışdığımız local / staging / prod modelinin eynisidir, sadəcə indi Vercel və ChatGPT Apps ilə bağlanıb. Bu, artıq böyüklər layihəsinin memarlığıdır, sonsuz localhost yox.

11. Vercel-ə deploy zamanı tipik səhvlər

Səhv №1: sirlər yalnız .env.local-da qalıb, Vercel-də isə yoxdur.
Çox yayılmış ssenari: lokalda hər şey işləyir, siz inamla “Deploy” basırsınız, tətbiq yığılır, amma production-da MCP alətləri 500 qaytarır və “Missing OPENAI_API_KEY” yazır. Səbəb sadədir: Vercel sizin lokal .env.local-ınızı bilmir. Eyni dəyişənləri ayrıca Vercel layihə ayarlarına (və düzgün scope-lara: Preview, Production) daxil etmək lazımdır.

Səhv №2: həssas məlumatlar üçün NEXT_PUBLIC_-dən istifadə.
Bəzən “tez işləsin” istəyi qalib gəlir və developer NEXT_PUBLIC_OPENAI_API_KEY yazır ki, açara klient kodundan çatsın. Nəticədə açar JS bundl-a düşür və istənilən istifadəçiyə əlçatan olur. Bu, sadəcə pis praktika deyil, açarın sızmasına və bloklanmasına birbaşa yoldur. Bütün sirlər — yalnız prefikssiz və yalnız server tərəfində.

Səhv №3: lokal və Vercel mühitlərinin uyğunsuzluğu.
Lokalda məhsullar üçün bir URL-ınız ola bilər (http://localhost:4000), Vercel-də başqa (https://api.gifts-staging.com), production-da isə üçüncü. Əgər env dəyişənlərinin səliqəli siyahısını aparmasanız və Preview/Production-da onların düzgün doldurulduğunu yoxlamasanız, asanlıqla belə vəziyyət alına bilər: production vidcet staging backend-ə gedir, staging vidcet isə production-a. Sadə intizam kömək edir: lazım olan bütün dəyişənləri sənədləşdirmək və hər mühitdə onları yoxlamaq.

Səhv №4: MCP endpoint-lər üçün icra vaxtı limitlərini nəzərə almamaq.
Lokalda hansısa ləng xarici sistemdən cavabı 30 saniyə gözləyə bilərsiniz və problemi hiss etməzsiniz. Vercel-də isə eyni funksiya 10–15 saniyədən sonra timeout alacaq və ChatGPT xəta görəcək. maxDuration təyin etməmisinizsə və MCP alətlərinin icra müddətini izləmirsinizsə, production-da bu, təsadüfi yıxılmalara çevrilə bilər.

Səhv №5: MCP vəziyyətini serverless funksiyanın yaddaşında saxlamağa cəhd.
Bəzən dialoq tarixçəsini və ya tövsiyə keşini birbaşa route handler faylında qlobal dəyişəndə let cache = {} saxlamaq çox “istəkli” görünür. Lokalda, dev server uzun müddət işləyərkən bu hətta “işləyə” də bilər. Amma Vercel-də hər serverless funksiya qısaömürlüdür və tez-tez yenidən yaradılır. Nəticədə bəzi sorğular “köhnə” cache-i, bəziləri “yeni”ni, bəziləri isə boşu “görür”. Bu isə təkrarlaması çətin qəribə bug-lar yaradır. Vəziyyət üçün xarici DB və ya KV saxlama lazımdır; bu dərsin səviyyəsində MCP endpoint-i tamamilə stateless saymaq daha yaxşıdır.