Next.js Uygulaması Netlify’ye Nasıl Deploy Edilir? 2026 Rehberi

Next. js Netlify deploy süreci, modern App Router uygulamalarında yalnız statik out klasörü yayınlamaktan ibaret değildir. Netlify’nin OpenNext tabanlı adapter’ı; SSR, ISR, Route Handlers, Server Actions, Middleware, React Server Components, streaming ve next/image gibi özellikler için gerekli Function, Edge Function, cache ve Image CDN yapılandırmasını otomatik oluşturabilir. En güvenilir kurulum, uygulamayı Git deposuna göndermek, Netlify’ye bağlamak ve build logunda adapter’ın hangi parçaları ürettiğini doğrulamaktır.

Bu rehber 13. 5 ve üzeri modern Next. js sürümlerini konu alıyor. Daha eski sürümler legacy runtime kapsamındadır. Framework, adapter ve deneysel özelliklerin durumu hızlı değiştiği için yayın gününde resmî uyumluluk tablosu yeniden kontrol edilmelidir.

Öne Çıkanlar

• Netlify, modern Next.js desteğini açık kaynak OpenNext adapter üzerinden sağlar.
• App Router, SSR, ISR, SSG, Server Components, Server Actions, Route Handlers ve streaming resmî destek tablosunda yer alır.
• Adapter, dinamik yollar için serverless Function; Middleware için Edge Function yapılandırabilir.
• next/image, varsayılan akışta Netlify Image CDN’den yararlanabilir.
• Next.js adapter sürümünü gerekmedikçe elle pinlemek önerilmez; otomatik güncellemeyi kapatmanın trade-off’u vardır.
• Environment variables, production ve Deploy Preview context’lerinde ayrı tutulmalıdır.
• “Deploy başarılı” sonucu feature parity kanıtı değildir; static, dynamic, server ve image davranışı ayrı test edilmelidir.

1. Netlify Next.js Desteği Hangi Özellikleri Kapsar?

Netlify’nin 23 Ağustos 2026’da erişilen resmî dokümanı, 13. 5 ve üzeri Next. js sürümleri için OpenNext adapter kullandığını belirtiyor. Adapter’ın görevi framework çıktısını Netlify primitive’lerine eşlemektir.

Next.js özelliği	Netlify çalışma katmanı
Static sayfalar	Deploy ve edge cache
SSR	Serverless Netlify Function
ISR / revalidation	Function + route/data cache
Route Handlers / API routes	Serverless Function
Server Actions	Serverless Function
Middleware	Edge Function
next/image	Netlify Image CDN
Full Route ve Data Cache	Netlify cache primitive’leri

Bu tablo “her deneysel özellik her sürümde kusursuz çalışır” anlamına gelmez. Netlify resmî destek ve e2e raporlarını yayımlar; özellikle yeni Next. js release’lerinde bilinen limitler incelenmelidir.

Dokümandaki önemli sınırlamalardan bazıları şunlardır: Edge runtime olarak işaretlenen SSR sayfaları Functions bölgesinde Node. js runtime ile çalışabilir; bazı rewrite hedefleri ve middleware işlem sırası standalone Next. js davranışından farklı olabilir; Node middleware’de filesystem veya C++ addon desteği sınırlıdır.

2. Örnek App Router Projesi Nasıl Hazırlanır?

Yeni bir App Router projesi:

``bash npx create-next-app@latest netlify-next-demo cd netlify-next-demo npm run dev ``

Kurulum sorularında App Router ve TypeScript tercih edilebilir. Kullanılan Next. js, React, Node ve package manager sürümlerini kaydedin. Ardından production build’i yerelde çalıştırın:

``bash npm ci npm run build npm run start ``

Basit test yapısı:

``text app/ ├── page.tsx ├── products/ │ └── [slug]/ │ └── page.tsx ├── api/ │ └── health/ │ └── route.ts └── actions.ts public/ └── demo.jpg ``

Static ana sayfa:

``tsx export default function HomePage() { return <main><h1>Netlify Next.js demo</h1></main>; } ``

Dynamic route:

```tsx type Props = { params: Promise<{ slug: string }> };

export default async function ProductPage({ params }: Props) { const { slug } = await params; return <main><h1>Ürün: {slug}</h1></main>; } ```

Route Handler:

``ts export async function GET() { return Response.json({ ok: true, checkedAt: new Date().toISOString() }); } ``

Bu örnekler sürüme bağlı API biçimleri açısından yayın öncesinde gerçek projede derlenmelidir. Kod bu taslak hazırlanırken çalıştırılmamıştır.

3. Git Repository Netlify’ye Nasıl Bağlanır?

Projeyi GitHub, GitLab veya desteklenen Git sağlayıcısına gönderin. Netlify dashboard’dan yeni proje oluşturup repository’yi seçin. Framework algılama Next. js’i tanımalı ve build komutunu önermelidir.

Tipik ayarlar:

``text Build command: next build veya npm run build Publish directory: framework adapter tarafından yönetilir ``

Next. js projesinde statik Vite sitesi gibi elle dist seçmeyin. next export veya output: "export" kullanmıyorsanız . next klasörünü ham statik publish directory olarak vermek doğru değildir. OpenNext adapter, . next çıktısından platforma uygun Function, cache ve asset yapılarını üretir.

Monorepo’da uygulamanın package directory’si doğru seçilmelidir. Workspace root’ta bulunan lockfile ve ortak paketler build’in hangi dizinden kurulacağını etkiler.

İlk deploy logunda şu noktaları arayın:

• Next.js sürümü,
• OpenNext/Netlify adapter algılaması,
• Static ve dynamic route sınıflandırması,
• Function paketleme adımları,
• Middleware/Edge Function üretimi,
• Image veya cache yapılandırması,
• Build warning ve bilinen feature notları.

4. Build ve Runtime Ayarları Nasıl Doğrulanır?

next build başarıyla bitse bile production runtime ayrıca test edilmelidir. Static page build sırasında üretilebilir; dynamic route ve Route Handler istek anında Function çalıştırabilir.

Doğrulama matrisi:

Özellik	Örnek URL/işlem	Beklenen kanıt
Static page	/	200 ve doğru HTML
Dynamic route	/products/demo	Parametreye göre render
Route Handler	/api/health	JSON ve doğru header
Server Action	Form gönderimi	Server-side işlem sonucu
Image optimization	next/image görseli	Optimize edilmiş image isteği
Middleware	Belirli path/header	Edge Function logu veya davranış

Function logları, status code ve browser çıktısı birlikte incelenmelidir. Tek bir 200 yanıtı, caching ve veri doğruluğunu kanıtlamaz.

Adapter sürümünü manuel pinlemek gerekmedikçe önerilmez. Netlify, 13. 5 ve üzeri Next. js sürümleri için adapter’ı güncel tutmayı ve proje build’inde uygun sürümü otomatik kullanmayı hedefliyor. Pinleme; geçici regression izolasyonunda yararlı olabilir fakat otomatik mimari iyileştirmeleri ve uyumluluk güncellemelerini durdurur. Pin kullanılacaksa neden, son kullanma tarihi ve kaldırma koşulu issue olarak kaydedilmelidir.

5. SSR, Dynamic Route ve Route Handler Nasıl Test Edilir?

SSR’ı gerçekten doğrulamak için yalnız kaynak kodu okumayın. İstek zamanında değişen bir değer veya request header kullanarak server-side davranışı görünür kılın. Örneğin kişisel veri içermeyen test header’ını sayfada gösterebilirsiniz.

Dynamic route testi:

``bash curl -i https://example.netlify.app/products/alpha curl -i https://example.netlify.app/products/beta ``

Route Handler testi:

``bash curl -i https://example.netlify.app/api/health ``

Kontrol edilecekler:

• Status code,
• content-type,
• Yanıt gövdesi,
• Function log zaman damgası,
• Cache header’ları,
• Hata durumunda yapılandırılmış yanıt,
• Preview ile production farkı.

Server Action testinde gönderimi iki kez deneyin ve idempotency ihtiyacını düşünün. Ödeme, e-posta veya kayıt oluşturan action’larda tekrar gönderim etkisi önemlidir. Demo testinde yalnız sentetik veri kullanın.

6. Image Optimization Nasıl Doğrulanır?

next/image bileşeni Netlify’de Image CDN ile çalışabilir:

```tsx import Image from "next/image";

export default function Hero() { return ( <Image src="/demo. jpg" alt="Demo ürün" width={1200} height={800} priority /> ); } ```

Browser Network sekmesinde gerçek image request URL’sini, formatı, boyutu ve cache davranışını inceleyin. “Image component render oldu” demek optimizasyonun beklenen varyantı ürettiğini kanıtlamaz.

Remote image kullanılıyorsa next. config içindeki izinli hostname/pattern doğru tanımlanmalıdır. Kullanıcı tarafından kontrol edilen keyfi URL’leri sınırsız proxy etmek güvenlik ve maliyet riski yaratabilir.

7. Environment Variables ve Preview Context Nasıl Yönetilir?

Next. js’te NEXT_PUBLIC_ önekli değerler client bundle’a dahil edilir. Private değerler server-only kodda kalmalıdır:

``env NEXT_PUBLIC_SITE_NAME=Demo DATABASE_URL=server-only-value ``

Production ve preview için ayrı kaynak kullanın:

Context	Database/API	E-posta	Ödeme
Production	Canlı	Gerçek gönderim	Live mode
Deploy Preview	Preview branch/sandbox	Allowlist veya devre dışı	Test mode

Deploy Preview’ın production database’e yazması, test verisiyle canlı veriyi karıştırabilir. Netlify Database branching veya üçüncü taraf sağlayıcının preview branch mekanizması varsa bunu kullanın; yoksa en azından ayrı schema/database oluşturun.

Environment variable değiştiğinde yeni deploy gerekir. Server Action veya Route Handler loguna değerin tamamını yazmayın; var/yok kontrolü ve güvenli tanımlayıcı yeterlidir.

8. Deploy Preview ve Rollback Akışı

Pull request açıldığında Netlify Deploy Preview oluşturabilir. İnceleme sırasında:

1. Static ana sayfayı açın. 2. Dynamic route’u farklı parametrelerle deneyin. 3. Route Handler’ın sandbox verisi döndürdüğünü doğrulayın. 4. Server Action’ı sentetik veriyle çalıştırın. 5. Image optimization request’ini inceleyin. 6. Middleware ve redirect davranışını test edin. 7. Function/Edge loglarında hata olmadığını kontrol edin.

Merge sonrasında production smoke test yapılmalıdır. Rollback önceki kod deploy’unu geri getirir; database migration ve dış servislerde yapılmış side effect’leri otomatik geri almaz. Şema değişikliklerini geriye uyumlu tasarlamak ve iki aşamalı migration kullanmak daha güvenli olabilir.

Next. js’te yeni deploy sırasında eski sayfayı açık tutan kullanıcılar, eski client bundle ile yeni server code arasında sürüm uyumsuzluğu yaşayabilir. Netlify skew protection bu riski azaltmak için deployment identifier kullanır; özellik opt-in olabilir ve açık fetch çağrılarında özel sınırlamalar bulunur. Gerçek ihtiyaca göre resmî dokümandan etkinleştirme ve sürüm şartlarını kontrol edin.

9. Sürüm Uyumluluğu ve Troubleshooting

Next.js sürümü 13.5’ten eski

Legacy runtime dokümanına bakın veya framework yükseltme planı oluşturun. Modern adapter davranışını eski projeye doğrudan varsaymayın.

Build başarılı, dynamic route 500 veriyor

Function logunu inceleyin. Eksik server environment variable, Node API uyumsuzluğu, database bağlantısı veya serialize edilemeyen veri nedeni olabilir.

Middleware farklı sırada çalışıyor

Netlify dokümanı header ve redirect değerlendirme sırasının standalone Next. js’ten farklı olabildiğini belirtir. Middleware, redirect ve header kombinasyonunu gerçek URL’lerle test edin.

Filesystem yazma hatası

Serverless/Edge çalışma zamanında kalıcı yerel disk varsaymayın. Kalıcı veri için Database, Blobs veya başka bir dış storage kullanın.

next/image remote görseli açmıyor

Remote pattern, domain izinleri ve kaynak sunucunun erişilebilirliği kontrol edilmelidir. Network yanıtı ve Image CDN URL’si incelenmelidir.

Form Netlify Forms’a düşmüyor

Next. js ile Netlify Forms, statik HTML formundan farklı ek yapılandırma gerektirebilir. Framework’e özel güncel entegrasyon dokümanını kullanın veya Route Handler/Function tabanlı kontrollü form endpoint’i tercih edin.

Adapter pinledikten sonra yeni özellik çalışmıyor

Pin, otomatik adapter güncellemesini kapatır. Sorunun hâlâ devam edip etmediğini yeni test branch’inde güncel adapter ile karşılaştırın.

Zorunlu Uygulama Testi

Briefin talep ettiği test için tek App Router projesinde aşağıdaki kanıtlar toplanmalıdır:

Özellik	Test sayısı	Sonuç
Static page	En az 2 istek	Uygulanmadı
Dynamic route	2 farklı slug	Uygulanmadı
Route Handler	Başarılı + hata durumu	Uygulanmadı
Server Action	En az 1 sentetik gönderim	Uygulanmadı
Image optimization	2 viewport/format	Uygulanmadı
Deploy Preview	1 PR	Uygulanmadı

> Editör notu — zorunlu özgün kanıt: Bu taslak hazırlanırken App Router projesi deploy edilmedi. Yayından önce Next. js, React, Node ve adapter sürümleri; commit SHA; test zamanı; region ve cold/warm koşulları kaydedilmeli. Her özellik için ekran, log veya HTTP çıktısı eklenmeli; çalıştırılmayan örnek “test edildi” diye sunulmamalıdır.

> Görsel notu: App Router route ağacı, OpenNext’in Function/Edge/Cache eşlemesi, deploy logu, SSR yanıtı ve Deploy Preview ekranı hazırlanmalıdır.

> İç link editör notu: GitHub deploy, Functions ve Deploy Previews yazıları yayına girdiğinde ilgili bölümlere bağlantı eklenmelidir.

Sık Sorulan Sorular

Next.js Netlify’de yalnız static export olarak mı çalışır?

Hayır. Modern adapter; SSR, ISR, Route Handlers, Server Actions, Middleware ve diğer dinamik özellikleri destekler. Gerçek proje özellikleri ayrıca test edilmelidir.

Publish directory olarak .next seçmeli miyim?

Standart OpenNext akışında ham . next klasörünü statik publish dizini gibi elle seçmek gerekmez. Framework algılama ve adapter yapılandırması kullanılmalıdır.

OpenNext nedir?

Next. js çıktısını farklı deployment platformlarının compute, cache ve routing primitive’lerine uyarlayan açık kaynak adapter yaklaşımıdır. Netlify modern Next. js desteğini bunun üzerinden sağlar.

Adapter sürümünü pinlemek doğru mu?

Genel öneri pinlememektir. Geçici regression izolasyonu için pin kullanılacaksa risk, kaldırma tarihi ve güncel adapter ile yeniden test planı yazılmalıdır.

Deploy Preview production ile aynı mı?

Kod büyük ölçüde aynı olabilir; URL, environment variables, veri kaynağı, erişim ve cache davranışı farklılaşabilir. Production smoke test yine gerekir.

Kaynaklar

• Next.js on Netlify
• Frameworks overview
• Deploy Previews
• Environment variables
• Functions overview
• OpenNext documentation

Sonuç

Next. js Netlify deploy, modern App Router projesini statik klasör olarak değil; route türüne göre Function, Edge Function, cache ve Image CDN kullanan hibrit bir uygulama olarak ele alır. Repository’yi bağlayıp adapter’a güvenmek başlangıcı kolaylaştırır; doğrulama ise static sayfa, dynamic route, Route Handler, Server Action, image optimization ve preview ortamını ayrı ayrı test etmeyi gerektirir. Framework ile adapter sürümlerini kaydedin, production verisini preview’dan ayırın ve limitleri resmî uyumluluk tablosuyla kontrol edin.

Next. js projenizi aynı test matrisiyle deploy etmek için [ücretsiz Netlify hesabı oluşturabilirsiniz](https://join. netlify. com/wmkqymu1heo2). Bu bir iş ortaklığı bağlantısıdır; bağlantı üzerinden kayıt olmanız veya ücretli plana geçmeniz halinde Ortak Alan komisyon kazanabilir.