Astro ve React Adacıkları Kurulumu

Bir Astro projesini başlatmak için, şablonu, TypeScript ayarlarını ve paket yöneticisini seçmenizi sağlayan etkileşimli bir sihirbazı çalıştıran npx create astro@latest kullanılır. Astro; boş şablon, blog şablonu ve dokümantasyon şablonları da dâhil olmak üzere birden çok başlangıç seçeneğini destekler.

Astro entegrasyonları bir projeye çatı desteği ekler. npx astro add react komutunun çalıştırılması @astrojs/react, react ve react-dom paketlerini otomatik olarak kurar ve React entegrasyonunu içerecek şekilde astro.config.mjs dosyasını günceller. Tüm kurulum tek bir komutla tamamlanır.

.astro dosyası, Astro'nun bileşen biçimidir. Bir ön bilgi bölümü (--- ayraçları arasındaki JavaScript) ve bir şablon bölümünden oluşur. Astro dosyası varsayılan olarak statik HTML üretir; açıkça bir istemci yönergesi eklemediğiniz sürece tarayıcıya JavaScript gönderilmez.

Bir React bileşenini Astro dosyasına aktarmak için standart ES modülü söz dizimi kullanılır: import Counter from './Counter.jsx'. Bir istemci yönergesi olmadan Astro, React bileşenini sunucu tarafında statik HTML olarak oluşturur ve bu HTML'yi tarayıcıya gönderir; bileşen için hiç JavaScript gönderilmez.

Astro şablonundaki bileşen etiketine client:visible eklemek, bileşeni bir adaya dönüştürür: <Counter client:visible />. Astro artık Counter bileşeninin JavaScript kodunu gönderir, görünüm alanına kaydırıldığında bileşene hidrasyon uygular ve onu etkileşimli hâle getirir. Yönerge olmadan bileşen statik HTML'dir.

Astro adaları olarak kullanılan React bileşenleri standart React ile yazılır; kancaları, durumu, efektleri ve herhangi bir React kitaplığını kullanabilirler. React bileşeninin içinde Astro'ya özgü bir API yoktur. Ada sınırı, bileşen kodunun içinde değil Astro şablonunda tanımlanır.

Her ada örneği bağımsız bir React ağacıdır. Aynı sayfadaki iki Counter adası durumu paylaşmaz. Paylaşılan bir duruma ihtiyacınız varsa üç seçeneğiniz vardır: adaları tek bir adada birleştirmek, serileştirilebilir durum için URL arama parametrelerini kullanmak veya nanostores gibi paylaşılan bir durum kitaplığı kullanmak.

@nanostores/react kitaplığı, herhangi bir adanın abone olabileceği hafif atomlar sağlar. Bir ada nano store atomuna yazar, başka bir ada ise bu atomu okur. Nano store'lar çatıdan bağımsız olduğundan bu yaklaşım, aynı sayfadaki React ve Vue adaları arasında da çalışır.

Astro İçerik Koleksiyonları, Markdown ve MDX dosyalarını yönetmek için tür güvenli bir yol sağlar. Zod ile bir koleksiyon şeması tanımlayın, Markdown dosyalarını src/content/ konumuna yerleştirin; Astro da tamamen türlendirilmiş sorgu işlevleri üretir. Bu, blog gönderileri, dokümantasyon ve ürün sayfaları için standart yaklaşımdır.

astro build komutunun çalıştırılması, statik HTML dosyalarından oluşan bir dist/ klasörü üretir. Astro her sayfa için sunucu tarafından oluşturulan içeriği içeren bir HTML dosyası ve yalnızca o sayfadaki adalar için gereken JavaScript paketlerini üretir. Hiç ada içermeyen sayfalarda hiç JavaScript üretilmez.

Statik çıktı, sunucu olmadan herhangi bir CDN'ye (Netlify, Vercel, Cloudflare Pages) dağıtılabilir. Sunucu tarafında oluşturma gereksinimleri (dinamik yollar, API uç noktaları) için Astro; Node.js, Vercel Edge, Cloudflare Workers ve Deno'ya yönelik SSR bağdaştırıcılarını destekler. Adalar her iki çalışma kipinde de aynı şekilde çalışır.

İçe aktarılmış bir React bileşenini istemci tarafında etkileşimli hâle getirmek için Astro şablonunda yapılması gereken en küçük değişiklik nedir?

npx astro add react komutuyla Astro'yu React ile kurun. Astro dosyaları varsayılan olarak statiktir; bir React bileşeni etiketine client: yönergesi eklemek, onu hidrasyon uygulanan bir adaya dönüştürür. React bileşenleri, Astro'ya özgü API'ler içermeyen standart React bileşenleridir. Durum her ada için yalıtılmıştır; nanostores adalar arası iletişimi sağlar. Derleme, yalnızca gereken ada JavaScript'ini içeren statik HTML üretir.