Next.js Kurulumu ve Yayına Alma

01Next.js Nedir, Kimler Kullanmalı?

Next.js, React üzerine kurulu bir web uygulama çatısıdır. React yalnızca arayüz bileşenlerini çizerken Next.js yönlendirme, sunucu tarafı sayfa üretimi, statik sayfa çıktısı, görsel optimizasyonu ve API uçları gibi ihtiyaçları hazır getirir.

En büyük farkı, sayfaları sunucuda HTML olarak üretebilmesidir. Arama motorları ve sosyal medya önizlemeleri içeriği doğrudan görür, ilk açılış hızlanır. Bu yüzden içerik ağırlıklı kurumsal siteler, katalog ve blog sayfaları için tek sayfa uygulamalara göre daha uygundur.

Yalnızca giriş gerektiren bir yönetim paneli geliştiriyorsanız daha sade bir yapı yeterli olabilir; bu senaryo için Vite ile React kurulumu rehberimize bakın.

02Önkoşullar

Next.js, desteklediği Node.js sürümleri konusunda seçicidir ve yeni ana sürümlerde eski Node desteğini bırakır. Bu yüzden nodejs.org üzerindeki güncel LTS sürümünü kurmak en sorunsuz yoldur.

• Node.js güncel LTS sürümü ve npm (Node ile gelir); pnpm, yarn ya da bun da kullanılabilir.
• Bir kod editörü; önerilen eklentilerle kurulum için VS Code kurulumu yazısına bakabilirsiniz.
• Git ve bir uzak depo (GitHub, GitLab): yayına alma süreçleri genellikle depodan beslenir.
• Kendi sunucunuza kuracaksanız SSH erişimi olan bir Linux sunucu.

03Node.js'i Kurun ve Doğrulayın

Node.js kurulumu işletim sistemine göre küçük farklar gösterir; Next.js komutları ise kurulumdan sonra her yerde aynıdır.

Windows

nodejs.org'dan LTS kurulum dosyasını indirin ya da winget kullanın; sonra terminali yeniden açın.

winget install OpenJS.NodeJS.LTS
node -v

macOS

Resmi paket ya da Homebrew ile kurabilirsiniz.

brew install node
node -v

Linux

Dağıtım depolarındaki sürüm eski kalabilir; nvm ile kurmak daha güvenlidir.

nvm install --lts
nvm use --lts
node -v

04create-next-app ile Proje Kurma

create next app sihirbazı resmi başlangıç aracıdır ve gerekli tüm paketleri tek seferde kurar. Komutu çalıştırdığınızda proje adı ve birkaç seçenek sorulur; kararsızsanız önerilen varsayılanları kabul etmek iyi bir başlangıçtır.

npx create-next-app@latest benim-sitem
cd benim-sitem
npm run dev

05App Router Yapısını Anlamak

Next.js App Router, yönlendirmeyi klasör yapısından üretir. app klasörü altındaki her klasör bir adres parçasıdır; o klasördeki page.tsx dosyası sayfayı, layout.tsx ise o bölümün ortak iskeletini tanımlar.

App Router'da bileşenler varsayılan olarak sunucu bileşenidir: sunucuda çalışır, veriyi doğrudan çekebilir ve tarayıcıya JavaScript göndermez. Tıklama, form durumu gibi etkileşim gereken bileşenlerin en üstüne use client yönergesini yazarak onları istemci bileşeni yaparsınız.

SEO İçin Metadata

Her sayfa ya da layout dosyası metadata nesnesi dışa aktararak başlık, açıklama ve Open Graph etiketlerini tanımlayabilir. Dinamik sayfalarda generateMetadata fonksiyonu kullanılır. Bu yapı, SEO uyumlu web tasarımı için gereken etiketleri sayfa düzeyinde yönetmeyi kolaylaştırır.

06Build Alma ve Ortam Değişkenleri

Yayına çıkmadan önce npm run build ile üretim derlemesi alın. Build çıktısı her sayfanın statik mi, dinamik mi üretildiğini listeler; beklemediğiniz bir sayfanın dinamik çıkması, gereksiz sunucu yükünün erken işaretidir.

Ortam değişkenleri .env.local dosyasında tutulur. Yalnızca NEXT_PUBLIC_ önekli değişkenler tarayıcıya gönderilir; veritabanı parolası ve API gizli anahtarları öneksiz kalmalı ve yalnızca sunucu kodunda kullanılmalıdır.

npm run build
npm run start

07Hangi Sayfa Nasıl Üretilmeli?

Next.js'in gücü, her sayfa için farklı bir render stratejisi seçebilmenizden gelir. Yanlış seçim ya gereksiz sunucu maliyeti ya da bayat içerik demektir; bu yüzden kuruluştan hemen sonra sayfalarınızı türlerine göre sınıflandırın.

Hakkımızda, hizmet ve iletişim gibi nadiren değişen sayfalar statik üretim için idealdir: derleme sırasında bir kez üretilir ve CDN'den saniyenin altında sunulur. Bir kurumsal web sitesi sayfalarının neredeyse tamamı bu gruptadır.

Blog ve ürün listeleri gibi ara sıra güncellenen sayfalarda belirli aralıklarla yeniden üretme (revalidate) iyi bir dengedir. Kullanıcıya özel panel, sepet ya da anlık müsaitlik gösteren rezervasyon ekranları ise her istekte sunucuda üretilmelidir. Bu son grup, otel ve acente gibi sektörel yazılımlarda sıkça karşılaşılan senaryodur ve veritabanı, önbellek ve yetkilendirme tasarımını birlikte düşünmeyi gerektirir.

08Next.js Deploy Seçenekleri

Next.js deploy için üç yaygın yol vardır. Hangisini seçeceğiniz trafik, bütçe, veri konumu ve ekibinizin sunucu yönetme deneyimine bağlıdır.

• Vercel: Next.js'in geliştiricisi olan şirketin platformu. Depoyu bağlarsınız, her gönderimde otomatik derleme ve önizleme adresi oluşur.
• Kendi Node.js sunucunuz: npm run start ile çalışan uygulamayı PM2 gibi bir süreç yöneticisi ayakta tutar, önüne Nginx konur. Tam kontrol sağlar ama bakım sorumluluğu sizdedir.
• Statik dışa aktarma: next.config dosyasında output: 'export' ayarıyla site düz HTML dosyalarına dönüşür. Sunucu bileşeni gerektiren dinamik özellikler bu modda çalışmaz.

PM2 ve Nginx ile Yayın

Ubuntu tabanlı bir sunucuda Node.js'i kurduktan sonra projeyi depodan çekip derleyin ve PM2 ile başlatın. PM2'nin startup komutu, ekrana yazdırdığı satırı sudo ile çalıştırmanızı ister; bu satır uygulamanın sunucu yeniden başladığında otomatik açılmasını sağlar.

git clone https://github.com/kullanici/benim-sitem.git
cd benim-sitem
npm ci
npm run build
sudo npm install -g pm2
pm2 start npm --name benim-sitem -- start
pm2 save
pm2 startup

server {
    listen 80;
    server_name ornek.com www.ornek.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

09Sık Hatalar ve Çözümleri

Next.js projelerinde karşılaşılan hataların çoğu sürüm uyumsuzluğundan ya da sunucu ile istemci kodunun karıştırılmasından doğar. Paket yönetimiyle ilgili sorunlarda npm komutları rehberi de yardımcı olur.