20 Ekim 2026’da npm’deki güncel Astro sürümü 7.4.1 idi. Aynı gün izlediğimiz 60 Astro temasının package.json dosyasında istenen ana sürüm dağılımı şöyleydi: Astro 7 isteyen 33, Astro 6 isteyen 7, Astro 5 isteyen 13, Astro 4 isteyen 5 ve Astro 2 isteyen 2 tema. Yani GitHub’dan beğendiğiniz bir Astro temasını kopyaladığınızda, büyük olasılıkla bir ya da birkaç ana sürüm geriden başlıyorsunuz.
Bu her zaman sorun değildir. Ama Astro’nun sürüm politikası, eski bir ana sürümde ne kadar rahat kalabileceğinizi belirler.
Astro sürüm numaraları ne söyler
Astro’nun yükseltme belgesi X.Y.Z biçimindeki sürüm numaralarını şöyle açıklar:
- Yama (Z): hata düzeltmeleri, iç düzenlemeler, performans işleri. Kodunuzda değişiklik gerekmez.
- Küçük sürüm (Y): yeni özellikler ve olası kullanımdan kaldırma uyarıları. Kodunuz değişmeden çalışmaya devam eder.
- Ana sürüm (X): kırıcı değişiklikler. Her biri ayrı bir “Upgrade to vX” rehberinde belgelenir.
Belgedeki önemli ayrıntı şudur: önceki ana sürüm yalnızca güvenlik düzeltmesi alır. Bir tema iki ana sürüm gerideyse, artık güvenlik düzeltmesi bile almayan bir sürümde olabilir. Deneysel özellikler bu kuralların dışındadır ve herhangi bir sürümde değişebilir.
Tema sayfalarımızdaki teknik kontrol listesi, temanın istediği sürümü güncel sürümle karşılaştırır: aynı ana sürümse olumlu, bir ana sürüm gerideyse dikkat, iki ve daha fazlaysa engel işareti gösterir. Dağılımın tamamı Astro temaları sayfasındaki sürüm grafiğinde.
Önce temanın kendisine bakın
Taşımaya başlamadan önce bir soruyu cevaplayın: tema güncelleniyor mu? Geliştirici temayı yakın zamanda yeni sürüme taşımışsa, sizin yapacağınız iş kendi değişikliklerinizi temanın yeni hâline aktarmaktır; sıfırdan taşımaktan çok daha kolaydır. Temanın son commit tarihini ve son 12 aydaki commit sayısını tema sayfasında görebilirsiniz.
Tema terk edilmişse taşıma tamamen size kalır. Bu durumda terk edilmiş temalar sayfasındaki bakımı süren alternatiflere de bakın; bazen bakımı süren bir temaya içeriğinizi taşımak, eski temayı yükseltmekten daha az iş çıkarır.
Yükseltme aracı
Astro’nun önerdiği yol @astrojs/upgrade aracıdır:
npx @astrojs/upgradepnpm için pnpm dlx @astrojs/upgrade, Yarn için yarn dlx @astrojs/upgrade. Belgeye göre araç Astro’yu ve tüm resmî entegrasyonları tek adımda en son sürüme yükseltir. Elle yapmak isterseniz npm install astro@latest ve kullandığınız entegrasyonların her biri için aynı komut gerekir.
Aracın yapmadığı şey, temanın kodunu değiştirmektir. Paketler güncellenir, kırıcı değişikliklerin gerektirdiği kod düzenlemeleri size kalır. Bunları her ana sürümün yükseltme rehberinden tek tek okumanız gerekir. Tema iki ana sürüm gerideyse, ara sürümün rehberini de atlamayın; örneğin 5’ten 7’ye geçerken önce 6’nın, sonra 7’nin rehberine bakın.
Astro 7’de temaları en çok etkileyen değişiklikler
Astro 7 yükseltme rehberinde başlık olarak geçen değişikliklerden temalar açısından öne çıkanlar:
Vite 8. Astro 7 hem geliştirme sunucusu hem de üretim derlemesi için Vite 8 kullanıyor. Rehber, çoğu projenin değişiklik gerektirmeyeceğini, ama Vite’in iç yapısına dayanan entegrasyon ve eklentilerin bozulabileceğini yazıyor. Temanızın astro.config dosyasında Vite eklentisi tanımlanmışsa ilk bakacağınız yer burasıdır.
Rust derleyici. Go tabanlı derleyicinin yerini Rust tabanlı bir derleyici aldı ve rehbere göre bu derleyici daha katı: kapatılmamış etiketler artık hata veriyor, geçersiz HTML iç içe yerleşimi de artık kendiliğinden düzeltilmiyor. Eski temalarda kapatılmamış bir <p> ya da <li> etiketi yıllarca sorun çıkarmamış olabilir; Astro 7’de derleme bu dosyalarda durur. Hata mesajı dosya ve satırı gösterir, düzeltme çoğu zaman tek satırlıktır.
Yeni varsayılan Markdown işleyicisi. .md ve .mdx dosyaları artık Sätteri adlı yeni işleyiciyle işleniyor. @astrojs/markdown-remark artık varsayılan olarak kurulmuyor; remark ya da rehype eklentisi kullanan bir tema, rehbere göre bu paketi kurup işleyiciyi unified() olarak ayarlamalı. Okuma süresi hesaplayan, başlıklara bağlantı ekleyen ya da kod bloklarını renklendiren temalar genellikle bu eklentileri kullanır; yükseltmeden sonra yazı sayfalarını mutlaka açıp kontrol edin. Ölçümümüzde 18 Astro temasının package.json dosyasında @astrojs/markdown-remark doğrudan bağımlılık olarak yazılıydı; bu temalar remark ekosistemine bağlı olduklarını açıkça gösteriyor ve Astro 7’ye geçerken işleyici ayarını yapmaları gerekecek.
Boşluk işleme. compressHTML ayarının varsayılanı true yerine 'jsx' oldu. Rehbere göre satır içi öğeler arasındaki boşluklar kaybolabilir; örneğin bir bağlantı ile yanındaki metin bitişik görünebilir. Rehber iki çözüm veriyor: araya {" "} eklemek ya da ayarı compressHTML: true yapmak. Tema genelinde bu sorunu görüyorsanız ikinci yol daha hızlıdır.
Ayrılmış dosya adı. src/fetch.ts ya da src/fetch.js artık gelişmiş yönlendirme için kullanılıyor. Temada bu adla bir yardımcı dosya varsa yeniden adlandırmanız ya da yapılandırmada fetchFile ayarını kullanmanız gerekiyor.
Kaldırılanlar. @astrojs/db paketi kaldırıldı; geçiş olarak Node’un yerleşik node:sqlite modülü, Drizzle ORM ya da başka bir veritabanı kütüphanesi öneriliyor. Görünüm geçişlerinde (astro:transitions) dışarıya açık bazı iç yardımcılar da kaldırıldı. Statik bir blog teması için bunlar nadiren önemlidir, ama sayfa geçiş animasyonu kullanan temalarda kontrol edin.
Adım adım taşıma planı
- Yeni bir dalda çalışın. Yükseltmeyi ana dalda değil ayrı bir dalda yapın; yayındaki site etkilenmesin.
- Mevcut çıktıyı saklayın. Yükseltmeden önce bir derleme alın ve
distklasörünü bir kenara kopyalayın. Sonradan karşılaştırma için en güvenilir referans budur. - Aracı çalıştırın.
npx @astrojs/upgradeile paketleri güncelleyin. - Derleyin ve hataları sırayla düzeltin. İlk hatalar genellikle derleyiciden (kapatılmamış etiketler) ve yapılandırmadan gelir.
- Görsel karşılaştırma yapın. Ana sayfa, bir yazı sayfası, etiket sayfası ve 404 sayfasını eski çıktıyla yan yana açın. Boşluk ve Markdown değişiklikleri hata vermez, yalnızca görünümde fark eder.
- Türkçe metinleri kontrol edin. Tarih biçimi, “Devamını oku” gibi kalıp metinler ve büyük harfli başlıklar yükseltmeden etkilenmemiş olmalı. Türkçeleştirme ayrıntıları için temayı Türkçeleştirmek yazısına bakın.
Ne zaman eski sürümde kalmak makul
Kişisel bir blog, iç ağda çalışan bir belge sitesi ya da yakında kapatacağınız bir kampanya sayfası için önceki ana sürümde bir süre kalmak makul olabilir; önceki ana sürüm hâlâ güvenlik düzeltmesi alıyor. İki ana sürüm geride olan bir temada ise bu güvence de yok. Bu durumda ya taşıma planı yapın ya da bakımı süren bir temaya geçin; seçenekleri bakım durumu sayfasında görebilirsiniz.