Astro’da tema, Hugo ya da Jekyll’daki gibi sitenize bağladığınız ayrı bir paket değildir; çoğu zaman projenin kendisidir. GitHub’daki bir Astro temasını kullanmak, o depoyu yeni bir projenin başlangıç kopyası olarak almak demektir. Bu yaklaşım ilk günü çok kolaylaştırır, ama altı ay sonra temanın yeni sürümünü almak istediğinizde neyle karşılaşacağınızı baştan bilmek gerekir.
Komut ve dal ayrıntısı
Astro’nun kurulum belgesi, herhangi bir GitHub deposunu şablon olarak kullanmak için şu biçimi verir:
npm create astro@latest -- --template kullanici/deponpm kullanırken bayraklardan önceki -- gereklidir; pnpm ve Yarn’da gerekmez. Belgenin altını çizdiği ayrıntı şu: komut deponun main dalını temel alır. Tema başka bir dalda yayımlanıyorsa dal adını # ile eklemeniz gerekir:
npm create astro@latest -- --template kullanici/depo#masterBu küçük bir ayrıntı gibi görünse de gerçek bir tuzaktır. 20 Ekim 2026 ölçümümüzde izlediğimiz 60 Astro temasının 12 tanesinin varsayılan dalı main değildi. Bu temalarda dal adını yazmadan çalıştırılan komut, belgeye göre aradığı main dalını bulamaz. Tema sayfalarımızdaki kurulum komutu, varsayılan dal main değilse dal adını kendiliğinden ekler; Astro temaları listesinden ilgili temaya geçip komutu oradan kopyalayabilirsiniz.
Node.js sürümü
Aynı belge, Astro için en az Node.js v22.22.0 ister ve v23 gibi tek sayılı sürümlerin desteklenmediğini yazar. Bilgisayarınızda eski bir Node.js varsa komut daha başta uyarı verir. Burada ikinci bir kontrol daha yapın: temanın package.json dosyasındaki engines alanı ya da depodaki .nvmrc dosyası daha dar bir aralık istiyor olabilir. Eski bir Astro sürümüne bağlı bir tema, yeni Node.js ile beklenmedik uyarılar verebilir.
Paket yöneticisini temaya göre seçin
Temanın deposunda hangi kilit dosyası varsa, geliştirici bağımlılıkları o paket yöneticisiyle sabitlemiştir. Ölçümümüzde kilit dosyası bulunan Astro temalarının dağılımı şöyleydi: 31 temada pnpm, 24 temada npm kilit dosyası vardı; 5 temada kökte kilit dosyası görünmüyordu ya da dosya listesi alınamadı. Kilit dosyası pnpm-lock.yaml olan bir temayı npm ile kurarsanız, npm kilit dosyasını görmezden gelir ve bağımlılıkların o günkü en yeni uyumlu sürümlerini çözer. Çoğu zaman bu sorun çıkarmaz; ama temanın geliştiricisinin hiç denemediği bir bağımlılık birleşimiyle çalışmaya başlamış olursunuz. Geliştiricinin kullandığı paket yöneticisini kullanmak, “bende çalışıyor” ile “sizde de çalışıyor” arasındaki farkı kapatır.
Bağımlılık listesi temanın ne getirdiğini söyler
Bir Astro temasını seçmeden önce package.json dosyasındaki bağımlılıklara bir dakika ayırın; tema hakkında ekran görüntüsünden fazlasını anlatır. İzlediğimiz 60 temada en sık görülen resmî entegrasyonlar şunlardı: @astrojs/sitemap 49 temada, @astrojs/check 47 temada, @astrojs/mdx 36 temada, @astrojs/rss 31 temada ve @astrojs/react 18 temada.
Bu listenin pratik karşılıkları var. Site haritası ve RSS entegrasyonu olan bir tema, arama motorları ve okuyucular için gereken iki dosyayı kendiliğinden üretir; yoksa sonradan eklemeniz gerekir. MDX entegrasyonu, yazıların içinde bileşen kullanmanıza izin verir ama yazılarınızı başka bir araca taşımayı zorlaştırabilir. React entegrasyonu olan bir tema, sayfaya istemci tarafında JavaScript yükleyen bileşenler içerebilir; sade bir blog için bu ek bir yüktür.
Stil tarafında Tailwind CSS belirleyicidir: temaların 49 tanesi Tailwind kullanıyordu ve bunların 36 tanesi Tailwind 4’e, 13 tanesi Tailwind 3’e bağlıydı. Tailwind 3’ten 4’e geçiş yapılandırma biçimini değiştirdiği için, eski sürüme bağlı bir temayı ileride yükseltmek ayrı bir iş olabilir. Her temanın entegrasyon listesini tema sayfasındaki teknik kontrol kutusunda görebilirsiniz.
Kopyaladıktan sonra tema sizin projenizdir
npm create astro şablonu indirir, yeni bir klasöre açar ve isterseniz yeni bir git deposu başlatır. Bu noktadan sonra temanın deposuyla bağınız yoktur. Geliştirici bir hatayı düzeltse ya da Astro’nun yeni ana sürümüne geçse, bu değişiklik projenize kendiliğinden gelmez.
Bunun üç pratik sonucu var:
- Temanın hangi commit’inden başladığınızı not edin. Proje kökünde küçük bir not dosyasına ya da ilk commit mesajına temanın deposunu ve o günkü son commit’in kısa kimliğini yazın. Sonradan neyin değiştiğini karşılaştırmak için bu tek bilgi yeter.
- İçeriği ve tema kodunu ayırın. Astro temalarında içerik genellikle
src/contentaltında, ayarlar isesrc/config.tsya da benzeri bir dosyada durur. Kendi değişikliklerinizi bu dosyalarla sınırladıkça, temadaki güncellemeleri sonradan elle taşımak kolaylaşır. - Bağımlılıkları kendiniz güncelleyin. Astro’nun yükseltme belgesi
npx @astrojs/upgradekomutunu önerir; bu komut Astro’yu ve resmî entegrasyonları birlikte günceller. Tema kodu bu komutla güncellenmez, yalnızca paketler güncellenir.
Temayı güncel tutmanın iki yolu
Yol 1, çatal (fork) ile çalışmak. Projeyi npm create astro yerine temanın deposunu GitHub’da çatallayarak başlatırsanız, çatalınız temanın deposuyla ilişkisini korur. GitHub’ın çatal belgesi, çatalı başka bir deponun (upstream) kopyası olarak başlayan, kendi ayarları ve izinleri olan ama kaynağıyla bağlantısını koruyan bir depo diye tanımlar. Bu yolda temanın yeni commit’lerini kendi dalınıza birleştirebilirsiniz; çakışmalar yalnızca sizin de değiştirdiğiniz dosyalarda çıkar. Dezavantajı görünürlüktür: belgeye göre herkese açık bir deponun çatalı herkese açıktır ve çatalın görünürlüğü tek başına değiştirilemez. Özel bir site için ayrı bir özel depo oluşturup temanın deposunu git’te ikinci bir uzak depo (remote) olarak eklemek benzer bir takip imkânı verir.
Yol 2, kopya ile çalışıp değişiklikleri seçerek almak. Şablonla başladıysanız, temanın deposunu ayrı bir klasöre klonlayıp not ettiğiniz commit ile son commit arasındaki farka bakabilirsiniz. Değişiklik az ise ilgili dosyaları elle taşımak çoğu zaman en hızlı yoldur.
Hangi yolu seçerseniz seçin, temanın gerçekten güncellenip güncellenmediğini önce kontrol edin. Ölçümümüzde Astro temalarının bakım durumu dağılımını bakım durumu sayfasında gösteriyoruz; yıllardır commit almamış bir temada güncelleme takibi yapmanın anlamı yoktur.
İlk derlemeden önce bakılacak beş dosya
package.json: Astro sürümü,enginesalanı,scriptsiçindekibuildkomutu.astro.config.mjs(ya da.ts):siteadresi,outputtürü (statik mi sunucu mu), entegrasyonlar.src/content.config.ts: içerik koleksiyonlarının alanları; kendi yazılarınızı bu şemaya uydurmanız gerekir.- Dil ve tarih ayarları: Türkçe bir site için
lang="tr"ve tarih biçimlendirmedetr-TRyerel ayarı. public/: temanın örnek görselleri ve favicon; yayına almadan önce kendi dosyalarınızla değiştirin.
Türkçe arayüz metni olan Astro temalarını Türkçe destekli temalar sayfasında listeliyoruz. Temanız eski bir Astro ana sürümüne bağlıysa, taşımaya başlamadan önce Astro’nun yükseltme belgesindeki ana sürüm rehberlerini sırayla okuyun; her ana sürüm için ayrı bir rehber var.