Astro Site Netlify’ye Nasıl Deploy Edilir? Static ve SSR Rehberi

Astro Netlify deploy iki farklı biçimde kurulabilir: tüm sayfaları build sırasında üreten statik site veya belirli sayfaları istek anında çalıştıran on-demand/SSR uygulaması. Statik ve sunucu özelliği kullanmayan projeler adapter olmadan astro build komutu ve dist çıktısıyla yayınlanabilir. SSR, server islands, middleware veya Netlify Image CDN entegrasyonu gerekiyorsa Astro’nun Netlify adapter’ını kurmak daha doğru başlangıçtır.

Bu ayrım önemlidir; her Astro projesine “SSR gerekli” demek de, her projeyi yalnız statik klasör gibi değerlendirmek de yanlıştır. Karar içerik güncelliği, kullanıcıya özel veri, oturum, cache ve operasyon ihtiyacına göre verilmelidir.

Öne Çıkanlar

• Astro’nun varsayılan yaklaşımı sayfaları build sırasında statik HTML olarak üretmektir.
• Netlify, Astro için astro build ve dist değerlerini önerebilir.
• Resmî Netlify önerisi çoğu projede Astro Netlify adapter’ını kurmaktır.
• Adapter gerektirmeyen saf statik proje de Netlify’ye deploy edilebilir.
• On-demand rendering Netlify Functions, dinamik middleware ise Edge Functions üzerinden çalışabilir.
• Adapter ile Astro <Image /> bileşeni Netlify Image CDN’den yararlanabilir.
• Astro 5.12 ve sonrası, adapter ile Netlify primitive’lerini normal Astro dev akışında yerel olarak sunabilir; 5.15’ten itibaren skew protection desteği bulunur.

1. Astro İçin Static ve SSR Deploy Farkı Nedir?

Statik Astro sayfası build sırasında HTML’e dönüştürülür. Ziyaretçi isteğinde hazır dosya edge cache’den sunulabilir. İçerik her istekte değişmiyorsa bu model basit ve öngörülebilirdir.

SSR veya Astro’nun güncel terminolojisiyle on-demand rendering, sayfayı istek sırasında server runtime’da üretir. Login session, kullanıcıya özel dashboard, sürekli güncellenen veri veya request’e bağlı içerik için kullanılır.

Kriter	Static	On-demand / SSR
Render zamanı	Build sırasında	İstek sırasında
Temel çalışma katmanı	Statik deploy/CDN	Netlify Functions
Kişiselleştirme	Client-side veya build varyantı	Request/session ile mümkün
Veri güncelliği	Yeni build veya revalidation gerekir	Her istekte/uygun cache ile güncel
Operasyon karmaşıklığı	Daha düşük	Function, cache ve veri kaynağı eklenir
Kredi etkisi	Deploy, request, bandwidth	Bunlara compute da eklenebilir

SSR’ın her zaman daha güncel ve daha iyi, static’in her zaman daha hızlı olduğu gibi genellemeler yapılmamalıdır. İyi cache’lenmiş SSR yanıtı hızlı olabilir; kötü optimize edilmiş statik sayfa büyük asset’ler nedeniyle yavaş olabilir.

2. Static Astro Projesi Netlify’ye Nasıl Bağlanır?

Yeni proje:

``bash npm create astro@latest astro-netlify-demo cd astro-netlify-demo npm install npm run dev ``

Yerel production build:

``bash npm run build ``

Varsayılan output:

``text dist/ ├── index.html ├── about/ │ └── index.html └── _astro/ ``

Projeyi Git repository’ye gönderin ve Netlify dashboard’dan bağlayın. Tipik değerler:

``text Build command: astro build veya npm run build Publish directory: dist ``

Saf statik proje için adapter zorunlu değildir. Netlify dokümanı, server-side özellik ve adapter üzerinden gelen Image CDN entegrasyonu gerekmiyorsa adapter olmadan deploy seçeneğini açıkça belirtir.

Manuel test için dist klasörü Netlify Drop’a da yüklenebilir. Ancak Git bağlantısı Deploy Preview ve otomatik build için daha uygundur.

3. Netlify Adapter Ne Zaman Gerekir?

Çoğu proje için Netlify’nin resmî önerisi Astro’nun Netlify adapter’ını kurmaktır:

``bash npx astro add netlify ``

Komut paketi yükler ve astro. config. mjs dosyasını günceller. Tipik yapı sürüme göre şöyle görünebilir:

```js import { defineConfig } from "astro/config"; import netlify from "@astrojs/netlify";

export default defineConfig({ adapter: netlify() }); ```

Adapter şu ihtiyaçlarda önem kazanır:

• On-demand/SSR sayfalar,
• Server islands,
• Session ve request tabanlı veri,
• Astro middleware’in dinamik sayfalarda çalışması,
• Netlify Image CDN ile <Image />,
• Netlify platform primitive’lerinin yerel geliştirmede kullanılması,
• Cache ve revalidation gibi platform entegrasyonları.

Yalnız birkaç Markdown sayfası üreten ve görselleri build sırasında optimize eden bir dokümantasyon sitesinde adapter eklememek makul olabilir. İleride SSR ekleme ihtimali varsa adapter’ı erken kurmak geçişi kolaylaştırabilir; fakat her dependency bakım yükü ve sürüm uyumluluğu getirir.

4. SSR veya On-Demand Rendering Nasıl Etkinleştirilir?

Astro sürümünüzün güncel render mode API’sini esas alın. On-demand sayfa, global veya route bazlı yapılandırmayla oluşturulabilir. Route bazlı yaklaşımın kavramsal örneği:

```astro --- export const prerender = false;

const requestTime = new Date(). toISOString(); ---

<html lang="tr"> <body> <h1>On-demand sayfa</h1> <p>İstek zamanı: {requestTime}</p> </body> </html> ```

Bu kod, kullanılan Astro ve adapter sürümünde gerçek build ile doğrulanmalıdır. Deploy sonrasında iki ayrı isteğin zaman değerini karşılaştırmak SSR davranışına dair kanıt sağlar; cache policy varsa aynı değerin dönmesi de beklenen olabilir.

Netlify’de on-demand rendering Functions ile çalışır. Bu nedenle Function logu, compute tüketimi, timeout, veri kaynağı bağlantısı ve cache ayarı izlenmelidir.

Session veya cookie kullanıyorsanız:

• Secure ve HttpOnly bayrakları,
• SameSite politikası,
• Preview ve production domain farkı,
• Kişisel yanıtların shared cache’e girmemesi,
• Logout ve expiry davranışı

ayrıca test edilmelidir.

5. Image CDN Nasıl Doğrulanır?

Adapter kurulu olduğunda Astro <Image /> bileşeni Netlify Image CDN üzerinden istek anında dönüşüm ve content negotiation kullanabilir. Örnek:

```astro --- import { Image } from "astro:assets"; import hero from "../assets/hero.jpg"; ---

<Image src={hero} alt="Örnek proje" width={1200} /> ```

Gerçek deploy’da Network sekmesinden şunları inceleyin:

• İstek hangi URL’ye gidiyor?
• Browser’a hangi format dönüyor?
• Görüntülenen genişliğe uygun boyut üretiliyor mu?
• Cache header’ları nedir?
• İlk ve tekrar isteğin davranışı nasıl?

Remote image için izin verilen domain/pattern yapılandırması gerekir. Kullanıcı kontrollü keyfi URL’leri sınırsız image proxy’ye açmak abuse ve maliyet riski yaratabilir.

Image CDN ihtiyacınız yoksa ve proje tamamen statikse adapter’sız deploy daha yalın olabilir. Bunun performans sonucunu varsaymak yerine aynı görseli iki yapılandırmada gerçek ölçümle karşılaştırın.

6. Middleware Nasıl Çalışır?

Astro middleware, pre-render edilen sayfalarda build zamanında; on-demand sayfalarda request sırasında çalışabilir. Netlify adapter, on-demand middleware’i Edge Functions üzerinden yürütebilir.

Middleware için uygun örnekler:

• Locale veya request header okuma,
• Hafif redirect,
• Response header ekleme,
• Session kontrolüne hazırlık,
• Basit deney varyantı.

Ağır database sorgusu, uzun işlem veya Node’a özgü paket gerektiren kod Edge runtime’a uygun olmayabilir. Edge Functions ile normal Functions’ın runtime, API ve gecikme özellikleri farklıdır.

Middleware’in static sayfada ne zaman çalıştığı ile SSR sayfada ne zaman çalıştığını ayrı test edin. “Middleware var, demek her istekte çalışıyor” varsayımı Astro’nun pre-render davranışı nedeniyle yanlış olabilir.

7. Yerel Geliştirmede Netlify Özellikleri Nasıl Kullanılır?

Netlify dokümanına göre Astro 5. 12 ve sonrasında, Netlify adapter kuruluysa Functions, Edge Functions, Blobs, Database, Cache API, Image CDN, redirects, headers, environment variables ve AI Gateway gibi primitive’ler normal npm run dev veya astro dev akışında kullanılabilir. Bu entegrasyon Vite tabanlı Netlify plugin altyapısından yararlanır.

Bu, her production davranışının yerelde birebir aynı olduğu anlamına gelmez. Şunlar production deploy’da yeniden doğrulanmalıdır:

• Gerçek domain/cookie davranışı,
• Bölgesel gecikme,
• Edge ve Function logları,
• Production secret scope’u,
• CDN cache ve purge,
• Third-party callback URL’leri.

Astro 5. 12’den eski bir projede aynı yerel davranışı beklemek yerine sürüm yükseltme veya Netlify CLI ihtiyacını resmî dokümandan kontrol edin.

8. Deploy Preview Nasıl Kullanılır?

Git bağlantılı Astro projesinde pull request, Deploy Preview oluşturabilir. Static ve SSR değişiklikleri aynı preview’da incelenebilir.

Preview kontrol listesi:

1. Static sayfanın HTML ve asset’leri doğru mu? 2. On-demand route Function logunda çalışıyor mu? 3. Preview environment variables sandbox değerlerini kullanıyor mu? 4. Image CDN isteği doğru kaynaktan geliyor mu? 5. Middleware beklenen route’larda çalışıyor mu? 6. Preview erişimi ve test verisi uygun mu? 7. Production merge sonrası yeniden smoke test gerekiyor mu?

Astro 5. 15 ve sonrası Netlify skew protection kullanarak deploy sırasında açık oturumdaki kullanıcının aynı deploy sürümüyle devam etmesine yardımcı olabilir. Bu davranışın sürüm ve feature koşulları yayın tarihinde kontrol edilmelidir.

9. Build Ayarları ve Yaygın Hatalar

dist klasörü oluşmuyor

Build komutu başarısız olabilir veya output ayarı değiştirilmiştir. Logdaki ilk hatayı ve astro. config. mjs dosyasını kontrol edin.

SSR sayfa build’de statik oluşuyor

Route’un render mode ayarı yanlış olabilir. Global output ve route bazlı prerender davranışını Astro sürüm dokümanından doğrulayın.

Adapter bulunamıyor

Paket lockfile’a eklenmemiş, yanlış package manager kullanılmış veya workspace resolution sorunu olabilir. Temiz kurulumla deneyin.

Remote image çalışmıyor

Allowed domain/pattern eksik olabilir. Kaynak sunucunun HTTPS ve response header davranışını da kontrol edin.

Yerelde çalışıyor, production’da 500 veriyor

Eksik environment variable, runtime API uyumsuzluğu veya veri kaynağı erişimi olabilir. Netlify Function/Edge logunu inceleyin.

Static route yanlışlıkla Function çalıştırıyor

Global SSR moduna geçilmiş veya route prerender ayarı yapılmamış olabilir. Build output ve route manifest’i inceleyin; gereksiz compute’u azaltmak için gerçekten statik kalabilen sayfaları pre-render edin.

10. Static mi SSR mı Seçilmeli?

Şu karar tablosu başlangıç sağlar:

İhtiyaç	Önerilen başlangıç
Blog, dokümantasyon, portföy	Static
İçerik CMS webhook ile güncelleniyor	Static + rebuild veya revalidation
Login sonrası kullanıcı dashboard’u	SSR/on-demand
Sayfanın küçük bölümü kişisel	Static + server island
Her istekte güncel fiyat/stok	SSR veya client fetch + cache stratejisi
Çok büyük sayfa sayısı, uzun build	On-demand veya hibrit
Minimum operasyon ve düşük compute	Static

Hibrit yaklaşım çoğu zaman en dengeli çözümdür: büyük içerik yüzeyi statik, yalnız gerçek zamanlı veya kişisel bölümler on-demand olabilir.

Zorunlu Static–SSR Testi

Aynı içerik sayfasını iki ayrı branch/deploy’da karşılaştırın:

Ölçüm	Static deploy	SSR deploy
Astro/Node sürümü	Kaydedilecek	Aynı tutulacak
Build süresi	Ölçülmedi	Ölçülmedi
Output yapısı	Ölçülmedi	Ölçülmedi
İlk yanıt	Ölçülmedi	Ölçülmedi
Tekrar istek/cache	Ölçülmedi	Ölçülmedi
Preview davranışı	Ölçülmedi	Ölçülmedi
Function çağrısı	Beklenmez	Doğrulanacak

Mikro benchmark’tan “static her zaman yüzde X hızlıdır” sonucu çıkarılmamalıdır. Testin region, bağlantı, cache sıcaklığı, sayfa boyutu ve örneklem sayısı açıklanmalıdır.

> Editör notu — zorunlu özgün kanıt: Bu taslak hazırlanırken aynı Astro sayfasının static ve SSR deploy’ları çalıştırılmadı. Yayından önce sürümler sabitlenerek iki branch deploy edilmeli; en az beş cold ve beş warm istek, build logu, output dosya ağacı ve Function invocation kanıtı eklenmelidir. Sayı uydurulmamalıdır.

> Görsel notu: Static vs SSR karar ağacı, astro. config. mjs, build output, Function logu, Image CDN request’i ve iki Deploy Preview ekranı hazırlanmalıdır.

> İç link editör notu: GitHub deploy, edge/cache ve Deploy Previews yazıları yayımlandığında ilgili bölümlere bağlantı eklenmelidir.

Sık Sorulan Sorular

Astro için Netlify adapter zorunlu mu?

Hayır. Saf statik ve adapter özelliklerine ihtiyaç duymayan proje astro build ve dist ile deploy edilebilir. Netlify çoğu proje için adapter’ı önerir.

Astro SSR Netlify’de nasıl çalışır?

On-demand rendering Netlify Functions üzerinden çalışır. Dinamik middleware ise Edge Functions kullanabilir.

Astro build output nedir?

Varsayılan static output dizini disttir. Özel yapılandırma varsa gerçek build çıktısı esas alınmalıdır.

Astro Image CDN için adapter gerekir mi?

Netlify dokümanı, Astro <Image /> bileşeninin Netlify Image CDN entegrasyonunu adapter ile sunar. Gerçek request davranışı deploy’da test edilmelidir.

Her sayfayı SSR yapmak mantıklı mı?

Genellikle hayır. İçerik build sırasında biliniyorsa pre-render operasyonu ve compute’u azaltabilir. Kişisel veya sürekli güncel route’lar on-demand tutulabilir.

Kaynaklar

• Astro on Netlify
• Netlify frameworks overview
• Deploy Previews
• Functions overview
• Edge Functions overview
• Astro Netlify adapter

Sonuç

Astro Netlify deploy için doğru yapı, projenin gerçekten ne kadar dinamik olduğuna bağlıdır. Blog veya dokümantasyon gibi içerikler statik dist çıktısıyla yalın biçimde yayınlanabilir. Session, on-demand veri, server island, dinamik middleware veya Netlify Image CDN gerektiğinde adapter ve hibrit render daha uygun olur. Kararı varsayıma değil, aynı sayfanın static ve SSR sürümlerini kontrollü biçimde ölçerek verin; preview ile production veri kaynaklarını da ayırın.

Astro projenizde static ve SSR akışlarını denemek 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.