Astro ile uygulamalı rehber: içerik odaklı siteler kurmak

Astro nedir, hangi ihtiyaçta seçilir?

Astro, içerik ağırlıklı web siteleri için tasarlanmış açık kaynaklı bir web çatısıdır. Temel fikri basittir: sayfalar varsayılan olarak derleme sırasında HTML'e dönüştürülür ve Astro bileşenleri tarayıcıya kendi çalışma zamanlarını göndermez. React, Vue veya Svelte gibi bir arayüz bileşeni de client:* yönergesi almadıkça tarayıcıda canlandırılmaz; etkileşim gereken yerde sayfanın yalnızca o parçası bir “ada” (island) olarak canlanır. Sayfaya kendiniz eklediğiniz <script> etiketleri ve canlandırılan adalar ise elbette JavaScript gönderir. Bu yazıyı hazırladığım 6 Ekim 2026 itibarıyla güncel kararlı sürüm 24 Eylül 2026'da yayımlanan Astro 7.3.5; kurulum belgesi Node.js 22.12.0 veya daha yeni bir sürüm istiyor ve 23 gibi tek numaralı Node sürümlerini desteklemiyor.

Astro 7 (22 Haziran 2026), .astro derleyicisini ve varsayılan Markdown/MDX işlemcisini Rust'a taşıdı, Vite 8 ve Rolldown'a geçti ve rota önbelleğini kararlı hâle getirdi. Bir önceki büyük sürüm Astro 6 (10 Mart 2026) ise geliştirme sunucusunu üretim çalışma zamanını kullanabilecek şekilde yeniden kurdu; yerleşik yazı tipi API'si, canlı içerik koleksiyonları ve İçerik Güvenliği Politikası (CSP) API'si getirdi. Eski bir eğitimi takip ediyorsanız bu değişiklikleri bilmek, kopyaladığınız kodun neden çalışmadığını anlamanızı kolaylaştırır.

Astro'yu seçmenin en güçlü gerekçesi içeriğin ön planda olduğu projelerdir: blog, dokümantasyon, portfolyo, kurumsal ve pazarlama sayfaları. Next.js, Nuxt veya SvelteKit gibi uygulama çatıları ise oturum açmış kullanıcıya göre değişen, durumu yoğun arayüzler için daha doğal bir başlangıç noktası olabilir. Doğru soru “hangisi daha iyi” değil, “bu projenin ne kadarı gerçekten etkileşimli ve ne kadarı her istekte taze olmalı” sorusudur. Bir yönetim paneli ya da kişiye özel bir ürün ekranı için Astro gereksiz bir dolambaç olabilir; bir içerik sitesi içinse çoğu zaman en sade yoldur.

Farkı somutlaştırmak için bileşen modellerine bakalım. Next.js'te sayfalar sunucu ve istemci bileşenlerinin birleşimidir ve React uygulaması tarayıcıda da yaşar. Nuxt, Vue uygulamasını sunucuda render edip tarayıcıda hidrasyonla canlandırır. SvelteKit de benzer biçimde tam bir uygulama çatısıdır. Astro ise ters yönden başlar: sayfa HTML'dir ve bir arayüz bileşeni ancak siz istediğinizde tarayıcıda canlanır. Hangi yaklaşımın sizin sitenizde daha az JavaScript göndereceğini kendi üretim derlemenizi ölçerek görün; buna karşılık çok sayıda ekranın aynı istemci durumunu paylaştığı bir uygulamada Astro'nun adalarını birbirine bağlamak ek iş çıkarabilir.

Size bir örnek göstereyim: okuduğunuz bu site de Astro ile üretilmiş statik bir yapı. Yayımlanan HTML'de /_astro/ klasöründen gelen, adında içerik parmak izi taşıyan CSS ve JavaScript dosyaları görülüyor. Bu, “hiç JavaScript yok” demek değil; sayfalarda dil seçimi ve küçük etkileşimler için satır içi betikler de var. Rehber boyunca benzer bir yapıyı, iki dilli bir portfolyo ve blog örneğiyle adım adım kuracağız.

01---02const title = 'Yemre Portfolio & Journal';03---04<html lang="tr">05  <head>06    <meta charset="utf-8" />07    <meta name="viewport" content="width=device-width" />08    <title>{title}</title>09    <meta name="description" content="Projeler, notlar ve teknik yazılar." />10  </head>11  <body>12    <main><h1>{title}</h1><p>Türkçe içerik ve teknik notlar.</p></main>13  </body>14</html>

Kurulum ve proje yapısı

Önce node -v ile Node.js sürümünüzün en az 22.12.0 olduğunu doğrulayın. Ardından resmî başlatıcıyla projeyi oluşturup geliştirme sunucusunu açın. Başlatıcı birkaç soru sorar ve bir şablon seçmenizi ister; bu rehber için en sade başlangıç şablonu yeterli.

01npm create astro@latest yemre-portfolio-journal02cd yemre-portfolio-journal03npm run dev

Astro'nun klasör düzeni kolay okunur. src/pages/ altındaki her dosya bir adres olur; src/components/ yeniden kullanılan bileşenleri, src/layouts/ ortak sayfa çerçevelerini, src/content/ Markdown içeriğini, src/assets/ işlenecek görselleri tutar. public/ klasöründeki dosyalar ise olduğu gibi kopyalanır. Önemli bir ayrıntı: src/content/ içindeki yazılar kendiliğinden sayfa olmaz; onları bir sayfa dosyası listeleyip rotaya dönüştürmelidir.

Yapılandırma astro.config.mjs dosyasında durur. Aşağıdaki örnek, site adresini, site haritası entegrasyonunu ve Türkçenin önek almadığı, İngilizcenin /en/ altında yayımlandığı iki dilli yönlendirmeyi tanımlıyor. site değerini mutlaka gerçek alan adınızla doldurun: canonical, site haritası ve RSS bağlantıları mutlak adres olarak bu değerden üretilir.

01npx astro add sitemap

01import { defineConfig } from 'astro/config';02import sitemap from '@astrojs/sitemap';03 04export default defineConfig({05  site: 'https://example.com',06  integrations: [sitemap()],07  i18n: {08    locales: ['tr', 'en'],09    defaultLocale: 'tr',10    routing: { prefixDefaultLocale: false },11  },12});

.astro bileşenleri, layout ve dosya tabanlı yönlendirme

Bir .astro dosyası iki bölümden oluşur. İki --- çizgisi arasındaki üst kısım (frontmatter), bileşen render edilirken sunucuda çalışan JavaScript veya TypeScript'tir: önceden üretilen sayfalarda derleme sırasında, isteğe bağlı render edilen sayfalarda her istekte. Burada veri çeker, props okur, değişken hazırlarsınız. Alt kısım ise HTML'e benzeyen şablondur. Bu kod tarayıcıya gönderilmez: bileşen HTML üretir ve işi biter. <slot /> ise bileşeni kullanan sayfanın içeriğinin yerleşeceği yerdir.

01---02interface Props {03  title: string;04}05const { title } = Astro.props;06---07<section>08  <h2>{title}</h2>09  <slot />10</section>

Layout'lar, birçok sayfanın paylaştığı HTML iskeletidir: <head>, üst menü ve ortak stiller. Sayfa, layout'u bir bileşen gibi kullanır ve kendi içeriğini onun içine yerleştirir. Dil bilgisini props olarak almak, her sayfada doğru lang niteliğini üretmeyi kolaylaştırır.

01---02import Header from '../components/Header.astro';03import '../styles/global.css';04 05interface Props {06  title: string;07  lang?: 'tr' | 'en';08}09const { title, lang = 'tr' } = Astro.props;10---11<html lang={lang}>12  <head>13    <meta charset="utf-8" />14    <meta name="viewport" content="width=device-width" />15    <title>{title}</title>16  </head>17  <body>18    <Header />19    <main><slot /></main>20  </body>21</html>

Dinamik adresler köşeli parantezle yazılır: src/pages/blog/[slug].astro her yazı için ayrı bir sayfa üretir. Statik derlemede Astro'nun hangi adresleri üreteceğini bilmesi gerekir; bunu getStaticPaths() fonksiyonu söyler. Aşağıdaki örnek, içerik koleksiyonundaki Türkçe yazıları alıp her biri için bir sayfa oluşturuyor ve Markdown gövdesini render() ile aldığı <Content /> bileşeniyle basıyor. İngilizce yazılar için aynı dosyayı src/pages/en/blog/[slug].astro olarak kopyalayıp filtreyi locale === 'en' yapmanız yeterli.

01---02import { getCollection, render } from 'astro:content';03 04export async function getStaticPaths() {05  const posts = await getCollection('blog', ({ data }) => data.locale === 'tr');06  return posts.map((post) => ({07    params: { slug: post.data.slug },08    props: { post },09  }));10}11 12const { post } = Astro.props;13const { Content } = await render(post);14---15<article>16  <h1>{post.data.title}</h1>17  <p>{post.data.description}</p>18  <Content />19</article>

İçerik koleksiyonları ve Markdown

İçerik koleksiyonları, Markdown dosyalarınızı tipli ve doğrulanmış verilere dönüştürür. Güncel API'de koleksiyonlar src/content.config.ts dosyasında tanımlanır; glob() gibi bir yükleyici dosyaları bulur, Zod şeması da her yazının başlık, açıklama, dil ve tarih gibi alanlarını derleme sırasında doğrular. Bir yazının tarihini yanlış yazar ya da zorunlu bir alanı unutursanız derleme hata verir; bu, yayına bozuk içerik çıkmasını önler. Zod'u astro/zod üzerinden içe aktardığınıza dikkat edin; eski eğitimlerdeki astro:content içe aktarması artık önerilen yol değil.

01import { defineCollection } from 'astro:content';02import { glob } from 'astro/loaders';03import { z } from 'astro/zod';04 05const blog = defineCollection({06  loader: glob({ base: './src/content/blog', pattern: '**/*.md' }),07  schema: z.object({08    title: z.string(),09    description: z.string(),10    slug: z.string(),11    locale: z.enum(['tr', 'en']),12    pubDate: z.coerce.date(),13    draft: z.boolean().default(false),14  }),15});16 17export const collections = { blog };

01---02title: Astro ile statik site geliştirme03description: Astro bileşenleri, içerik koleksiyonları ve islands mimarisi.04slug: astro-rehberi05locale: tr06pubDate: 2026-10-0607draft: false08---09 10## İlk bölüm11 12Yazının Markdown gövdesi burada.

İngilizce sürüm için aynı klasöre locale: en ve benzersiz bir slug taşıyan ikinci bir dosya ekleyin. Dil klasörleri açmak yerine dili bir alan olarak tutmak, basit [slug] rotasıyla birlikte daha az sürpriz çıkarır, çünkü yükleyici klasör yolunu kaydın kimliğine dahil eder. MDX gerekiyorsa resmî MDX entegrasyonunu kurup yükleyici desenini genişletin; gerekmiyorsa düz Markdown yeterlidir.

getCollection() sonuçlarının sırası garanti değildir; tarih sıralı bir liste istiyorsanız açıkça sıralayın. Taslakları filtrelemek de aynı yerde yapılır.

01---02import { getCollection } from 'astro:content';03 04const posts = (await getCollection('blog', ({ data }) =>05  data.locale === 'tr' && !data.draft06)).sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());07---08<ul>09  {posts.map((post) => (10    <li><a href={'/blog/' + post.data.slug + '/'}>{post.data.title}</a></li>11  ))}12</ul>

Her istekte taze olması gereken veriler için derleme zamanlı koleksiyonlar uygun değildir; bir stok bilgisi ya da sık güncellenen bir liste, derlendiği andaki hâliyle donar. Bu durumlar için Astro 6 ile gelen canlı içerik koleksiyonları (Live Content Collections) veriyi istek anında sorgular, ancak bunun için bir adaptör ve isteğe bağlı render gerekir. Blog yazıları gibi nadiren değişen içerik için ise derleme zamanlı koleksiyonlar yeterlidir: veri derleme sırasında bir kez okunur ve adaptör gerekmez.

Islands mimarisi: etkileşimi seçerek eklemek

Astro'nun en ayırt edici fikri “islands” mimarisidir. Sayfanın büyük bölümü statik HTML olarak kalır; yalnızca etkileşim gereken parçalar, örneğin bir arama kutusu ya da tema seçici, bir arayüz kütüphanesiyle tarayıcıda canlandırılır. Bunun için önce resmî entegrasyonu kurarsınız (örneğin npx astro add react). Önemli nokta şu: bir React bileşenini içe aktarmak tek başına onu tarayıcıda çalıştırmaz. Bileşen client:* yönergesi olmadan kullanılırsa sunucuda HTML'e dönüştürülür ve tarayıcıya JavaScript gitmez.

01---02import PostSearch from '../../components/PostSearch';03---04<h1>Yazılar</h1>05<PostSearch client:visible />

01import { useState } from 'react';02 03export default function PostSearch() {04  const [query, setQuery] = useState('');05  return (06    <label>07      Yazılarda ara08      <input09        value={query}10        onChange={(event) => setQuery(event.currentTarget.value)}11      />12    </label>13  );14}

Yönerge, adanın ne zaman canlanacağını belirler. Bunlar süre değil olay tanımıdır; “şu kadar milisaniyede yüklenir” diye bir garanti vermezler:

• client:load: sayfa yüklenirken JavaScript'i yükler ve canlandırır; yalnızca hemen gereken etkileşimler için kullanın.
• client:idle: ilk yüklemeden sonra tarayıcı boşta kaldığında canlandırır.
• client:visible: bileşen ekranda görünür olduğunda canlandırır; sayfanın altındaki parçalar için idealdir.
• Yönerge yoksa: bileşen yalnızca HTML olarak kalır, tarayıcıda canlanmaz.

Sayfalar arası geçişlerde uygulama hissi istiyorsanız ClientRouter bileşenini isteğe bağlı olarak ekleyebilirsiniz. Ancak bu, betiklerin her sayfa geçişinde yeniden çalışmadığı anlamına gelir; yeniden başlatılması gereken kodu astro:page-load olayına bağlayın ve gezinmeyi mutlaka test edin.

01---02import { ClientRouter } from 'astro:transitions';03---04<head>05  <ClientRouter />06</head>

Statik, isteğe bağlı render, Server Islands ve Actions

Astro'da varsayılan çıktı statiktir: her sayfa derleme sırasında bir kez üretilir ve herkese aynı HTML sunulur. Bazı sayfaların her istekte üretilmesi gerekiyorsa, örneğin çerez okuyan bir önizleme sayfası, bir adaptör eklersiniz. Adaptör, Astro'nun Node, Vercel, Netlify veya Cloudflare gibi bir çalışma zamanında sunucu kodu çalıştırmasını sağlar. Sonra yalnızca o sayfada prerender = false diyerek isteğe bağlı render'a geçersiniz; geri kalan her şey statik kalır.

01npx astro add node

01import { defineConfig } from 'astro/config';02import node from '@astrojs/node';03 04export default defineConfig({05  output: 'static',06  adapter: node({ mode: 'standalone' }),07});

01---02export const prerender = false;03const language = Astro.cookies.get('preview-language')?.value ?? 'tr';04---05<p>Preview language: {language}</p>

Projenin çoğu isteğe bağlıysa tersini yapın: output: 'server' ayarlayıp statik kalması gereken sayfalarda prerender = true kullanın. Eski eğitimlerde görebileceğiniz output: 'hybrid' değeri güncel bir seçenek değil; “hibrit” yalnızca statik ve isteğe bağlı sayfaları karıştıran bir projeyi tarif etmek için kullanılan bir terim.

Server Islands bir adım daha ileri gider: sayfanın tamamı önceden üretilir, ama tek bir bileşen server:defer ile ertelenir ve istek anında sunucuda render edilir. Bu sırada slot="fallback" içindeki yer tutucu görünür. Bu, React adasıyla aynı şey değildir; burada tarayıcıda canlanan bir bileşen yok, sunucudan sonradan gelen bir HTML parçası var. Kişiye özel küçük bir selamlama veya sık değişen bir sayaç için uygundur ve bir adaptör gerektirir.

01---02const visitorName = Astro.cookies.get('visitor')?.value ?? 'ziyaretçi';03---04<p>Hoş geldin, {visitorName}.</p>

01---02import VisitorNote from '../components/VisitorNote.astro';03---04<VisitorNote server:defer>05  <span slot="fallback">Ziyaretçi bilgisi yükleniyor…</span>06</VisitorNote>

Form gönderimi gibi sunucu işleri için Astro Actions tipli sunucu fonksiyonları sunar. Girdiyi Zod ile çalışma zamanında doğrular ve hataları standart bir biçimde döndürür. Aşağıdaki örnek iletişim formunu doğruluyor; gerçek bir projede e-postayı güvenilir bir posta servisine iletir, bu servisin gizli anahtarını da astro:env ile yalnızca sunucuda tutarsınız. Actions da bir adaptör ister.

01import { defineAction } from 'astro:actions';02import { z } from 'astro/zod';03 04export const server = {05  contact: defineAction({06    input: z.object({07      email: z.string().email(),08      message: z.string().min(1).max(2000),09    }),10    handler: async ({ email, message }) => {11      // Send to a trusted mail service here; do not expose its secret in client code.12      return { accepted: Boolean(email && message) };13    },14  }),15};

İki dilli yönlendirme ve görseller

İkinci bölümdeki yapılandırma, Türkçeyi önek almayan varsayılan dil yaptı. Türkçe sayfaları src/pages/ altına, İngilizce sayfaları src/pages/en/ altına koyduğunuzda Astro bunları / ve /en/ adreslerine eşler. Bileşenlerde doğru dildeki bağlantıları üretmek için astro:i18n yardımcılarını kullanabilirsiniz. Her dil için ayrı sayfa başlığı, açıklama ve içerik kaydı tutmayı unutmayın; yönlendirme tek başına çeviri yapmaz.

Görseller için astro:assets modülündeki <Image /> bileşeni, projeye içe aktarılan görselleri derleme sırasında optimize eder. Genişlik ve yükseklik vermek sayfa kaymasını önler, anlamlı bir alt metin de erişilebilirlik için şarttır. public/ klasöründeki, olduğu gibi sunulması gereken dosyalar için düz <img> kullanın; uzak sunuculardaki görselleri optimize etmek ise ayrıca izin listesi yapılandırması ister.

01---02import { Image } from 'astro:assets';03import portrait from '../assets/portrait.webp';04---05<Image06  src={portrait}07  alt="Yunus Emre Balçın"08  width={640}09  height={640}10/>

SEO, performans ve test

Astro statik HTML ürettiği için arama motorları içeriği doğrudan okur; yine de başlık, açıklama, canonical ve dil etiketlerini doğru kurmak size kalır. Ortak <head>'i layout'ta toplamak en temiz yoldur. Canonical adresi, yapılandırmadaki site değeri tanımlıysa Astro.site ile mutlak olarak üretebilirsiniz. İki dilli bir sitede her sayfanın iki dildeki karşılığını hreflang ile göstermesi gerekir; bu adresleri her sayfa kendi çevirisine göre layout'a props olarak vermeli, çevirisi olmayan sayfada ise alternatif bağlantı hiç üretilmemelidir.

01---02interface Props {03  title: string;04  description: string;05  lang?: 'tr' | 'en';06  alternates?: { tr?: string; en?: string };07}08const { title, description, lang = 'tr', alternates = {} } = Astro.props;09const canonical = Astro.site ? new URL(Astro.url.pathname, Astro.site) : undefined;10---11<html lang={lang}>12  <head>13    <meta charset="utf-8" />14    <meta name="viewport" content="width=device-width" />15    <title>{title}</title>16    <meta name="description" content={description} />17    {canonical && <link rel="canonical" href={canonical} />}18    {alternates.tr && <link rel="alternate" hreflang="tr" href={alternates.tr} />}19    {alternates.en && <link rel="alternate" hreflang="en" href={alternates.en} />}20  </head>21  <body><slot /></body>22</html>

Site haritası için @astrojs/sitemap entegrasyonu yeterlidir. RSS beslemesi ise statik bir uç nokta olarak yazılır: src/pages/rss.xml.ts dosyası yazı koleksiyonunu okuyup resmî @astrojs/rss paketiyle beslemeyi üretir.

01npm install @astrojs/rss

01import rss from '@astrojs/rss';02import { getCollection } from 'astro:content';03 04export async function GET(context) {05  const posts = await getCollection('blog', ({ data }) =>06    data.locale === 'tr' && !data.draft07  );08  return rss({09    title: 'Yemre Portfolio & Journal',10    description: 'Türkçe teknik yazılar.',11    site: context.site,12    items: posts.map((post) => ({13      title: post.data.title,14      description: post.data.description,15      pubDate: post.data.pubDate,16      link: '/blog/' + post.data.slug + '/',17    })),18  });19}

Performans tarafında Astro'nun size verdiği avantajı korumak sizin elinizde: etkileşimsiz içeriği .astro HTML'i olarak bırakın, yalnızca tarayıcı durumu gereken arayüzü canlandırın, doğru yönergeyi seçin ve görsellere boyut verin. Hız iddialarını ölçmeden yazmayın; kendi üretim derlemenizi ölçün. Test için üretim önizlemesine karşı çalışan küçük bir Playwright testi iyi bir başlangıçtır.

01import { test, expect } from '@playwright/test';02 03test('home page has a title and main heading', async ({ page }) => {04  await page.goto('http://localhost:4321/');05  await expect(page).toHaveTitle(/Yemre Portfolio/);06  await expect(page.getByRole('heading', { level: 1 })).toBeVisible();07});

Testin çalışması için Playwright'ı ve tarayıcılarını kurun. playwright.config.ts içindeki webServer ayarı, testlerden önce üretim derlemesini önizleme sunucusunda kendisi başlatır; test bu sunucunun adresine (varsayılan olarak http://localhost:4321) gider.

01import { defineConfig } from '@playwright/test';02 03export default defineConfig({04  testDir: './src/test',05  webServer: {06    command: 'npm run preview',07    url: 'http://localhost:4321/',08    reuseExistingServer: !process.env.CI,09  },10  use: { baseURL: 'http://localhost:4321/' },11});

01npm init playwright@latest   # @playwright/test + tarayıcılar / browsers02npm run build03npx playwright test          # webServer önizlemeyi kendisi açar / starts the preview itself

Yayına alma ve sık yapılan hatalar

Varsayılan statik çıktıda npm run build her şeyi dist/ klasörüne yazar; bu klasörü herhangi bir statik barındırmaya yükleyebilirsiniz. İsteğe bağlı render, Actions veya Server Islands kullanıyorsanız ilgili resmî adaptörü kurup sağlayıcının güncel yayın rehberini izleyin; Node adaptöründe derlemeden sonra sunucu girişini çalıştırırsınız.

01# Varsayılan statik çıktı: dist/ klasörünü statik barındırmaya yükleyin02# Default static output: upload the dist/ folder to a static host03npm run build

01# Yalnızca Node adaptörü kuruluysa / Only when the Node adapter is installed02npm run build03node ./dist/server/entry.mjs

Yayından önce aşağıdaki listeyi kontrol edin; bunlar Astro projelerinde en sık karşılaşılan hatalar:

• Bir .astro bileşeninin tarayıcıda çalıştığını varsaymayın; etkileşim için bir ada veya betik kullanın.
• Her bileşene client:load eklemeyin; her etkileşim için yönergeyi bilinçli seçin.
• Statik derlemede dinamik sayfa için getStaticPaths() yazmayı unutmayın; koleksiyon kayıtları kendiliğinden rota olmaz.
• Zod'u astro:content yerine astro/zod üzerinden içe aktarın; eski src/content/config.ts örneklerini kontrol etmeden kopyalamayın.
• API, oturum, Action veya Server Island'ın adaptörsüz düz statik barındırmada çalışmasını beklemeyin.
• output: 'hybrid' kullanmayın; static veya server ile sayfa bazında prerender kullanın.
• Gizli anahtarları istemciye açık değerlere koymayın; PUBLIC_ değişkenleri ve astro:env/client herkese açıktır.
• site değerini tanımlamadan mutlak canonical, site haritası veya RSS bağlantısı beklemeyin.
• Derlemeden sonra iki dildeki canonical, hreflang ve site haritası adreslerini mutlaka kontrol edin.

Astro'nun gücü, varsayılan olarak az şey yapmasından gelir: HTML üretir ve geri çekilir. Etkileşimi, sunucu kodunu ve canlı veriyi ancak gerçekten ihtiyaç duyduğunuz yere eklersiniz. Bu rehberdeki portfolyo ve blog örneğini kendi projenize uyarlarken bu disiplini koruyun; yeni bir ada ya da adaptör eklemeden önce tarayıcıya, sunucuya ve yayın sürecine ne kattığını kendi projeniz için değerlendirin.