AstroJS: Kapsamlı Türkçe Geliştirici Rehberi

Bu rehber, AstroJS ile web geliştirme süreçlerini, kurulumdan ileri seviye veri yönetimine kadar tek bir kaynakta toplamaktadır.

1. AstroJS Nedir?

Astro, hızlı ve içerik odaklı web siteleri oluşturmak için geliştirilmiş, hepsi bir arada bir web framework'üdür. JavaScript ile yazılmış olup açık kaynaklı, basit ve güçlü bir yapıya sahiptir.

Eğer kurulum yapmadan önce tarayıcınızda denemek isterseniz, astro.new adresini ziyaret edebilir ve hazır şablonlarla (StackBlitz üzerinde) çalışan bir sürümü inceleyebilirsiniz.

2. Kurulum ve Başlangıç

Astro CLI (Komut Satırı Arayüzü) kullanarak projenizi hızlıca oluşturabilirsiniz.

Gereksinimler

*
Node.js: v16.12.0 veya daha yüksek bir sürüm gereklidir.

*
Editör: VSCode önerilmektedir.

*
Terminal: Komut satırı erişimi gereklidir.

Proje Oluşturma Adımları

Terminali projenizi oluşturmak istediğiniz klasörde açın ve aşağıdaki komutu girin:

npm create astro@latest

2.
Konum Seçimi: "Yeni Projenizi Nereye Oluşturmak İstiyorsunuz" sorusuna . (nokta) ile cevap verirseniz bulunduğunuz klasöre kurulum yapar. Farklı bir isim yazarsanız o isimde klasör oluşturur.

Şablon Seçimi:

*
Include Sample File: Hazır şablon dosyaları ile gelir, başlangıç için idealdir.

*
Use blog template: Markdown tabanlı hazır blog şablonu oluşturur.

*
Empty: Sadece index dosyasını oluşturur, sıfırdan başlamak isteyenler içindir.

4.
Bağımlılıklar (Dependencies): "Install Dependencies?" sorusuna Yes diyerek gerekli paketleri yükleyin.

TypeScript: TypeScript kullanıp kullanmayacağınızı seçebilirsiniz. No seçseniz bile sonradan ekleyebilirsiniz.

Git: GitHub deposu oluşturmak isteyip istemediğinizi seçebilirsiniz.

Projeyi Çalıştırma

Kurulum tamamlandıktan sonra terminale şu komutu girin:

npm run dev

Her şey yolunda giderse projeniz http://localhost:4321 (veya port doluysa 3000, 3001 gibi portlarda) çalışmaya başlar. Astro, src/ dizinindeki değişiklikleri canlı olarak dinler, sunucuyu yeniden başlatmanız gerekmez.

İpucu: Hazır bir GitHub şablonu kullanmak isterseniz (örneğin "astro-paper"):

npm create astro@latest -- --template satnaing/astro-paper

komutunu kullanabilirsiniz.

3. Editör Ayarları

Astro her editörle çalışsa da, geliştirici deneyimi için VS Code önerilir.

VS Code Yapılandırması

Resmi Astro VS Code Uzantısı şunları sağlar:

*
.astro dosyaları için sözdizimi vurgulama (syntax highlighting).

TypeScript türü bilgileri.
Kod tamamlama ve Intellisense.

Diğer Editörler ve Araçlar

*
JetBrains (WebStorm vb.): Resmi eklenti Marketplace üzerinden yüklenebilir.

*
Topluluk Eklentileri: Vim, Neovim ve Nova için topluluk tarafından geliştirilen eklentiler mevcuttur.

*
ESLint: Kod denetimi için topluluk tarafından yönetilen eslint-plugin-astro eklentisi kurulabilir.

Prettier: Kod biçimlendirme için kullanılır. Astro VS Code uzantısında dahili olarak gelir, ancak harici kullanım için prettier-plugin-astro yüklenebilir.

4. Astro'nun Temel Özellikleri ve Dosya Yapısı

Projenin ana sayfası src/pages/index.astro dosyasıdır. Bir Astro dosyasının yapısı şöyledir:

Code Fences (Kod Blokları)

Dosyanın en üstünde --- (üç çizgi) arasında yer alan kodlar sunucu tarafında (server-side) çalışır. JavaScript değişkenleri, import işlemleri ve fonksiyonlar burada tanımlanır.

---
const title = "AstroJS";
const sayi = 5;
---
<h1>{title}</h1>
<p>{sayi}</p>

. Değişkenleri HTML içinde {degiskenAdi} şeklinde kullanabilirsiniz.

Layouts ve Slotlar

Kod tekrarını önlemek için Layout (Şablon) yapısı kullanılır.

Layout Dosyası (src/layouts/Layout.astro): İçerisinde <slot /> etiketi barındırır. Sayfa içeriği bu etiketin olduğu yere yerleşir.
Kullanımı:

import Layout from '../layouts/Layout.astro';
<Layout>
  <main>Sayfa İçeriği</main>
</Layout>

Bileşenler (Components)

Parçalı dosya yapısı ile kodları modüler hale getirebilirsiniz. Örneğin, bir kart yapısını Card.astro olarak kaydedip ana sayfada defalarca kullanabilirsiniz.

Props (Veri Aktarımı)

Bir bileşene veri göndermek için Props yapısı kullanılır. TypeScript ile tip tanımlaması yapılabilir.

Baslik.astro:

---
interface Props {
    baslik: string;
}
const { baslik } = Astro.props;
---
<h1>{baslik}</h1>

Kullanımı (index.astro):

<Baslik baslik="Anasayfa" />

Stiller (CSS)

Astro'da CSS iki şekilde tanımlanır:

1.
Scoped (Varsayılan): <style> etiketi içine yazılır, sadece o dosyayı etkiler.

2.
Global: <style is:global> şeklinde yazılır, tüm projeyi etkiler.

Döngüler ve Koşullar

Map Döngüsü: Dizileri ekrana yazdırmak için kullanılır.

{dizi.map((item) => <p>{item}</p>)}

If/Else (Koşullar): JavaScript mantığı ile koşullu render yapılabilir.

{sayi ? <p>{sayi}</p> : <p>Sayı yok</p>}

5. Diğer Frameworklerle Çalışma (Integrations)

Astro, React, Vue, Svelte gibi popüler frameworkleri projeniz içinde kullanmanıza olanak tanır.

Kurulum Mantığı

Genel kurulum komutu: npx astro add [framework_adi] şeklindedir. Eğer sunucu çalışıyorsa durdurup kurulumu yapmalısınız.

Desteklenen Frameworkler ve Örnekler

Vue.js:

Kurulum: npx astro add vue -y.
Kullanım: Bileşeni import edin ve <Hesap client:load /> şeklinde kullanın. client:load gibi direktifler interaktivite için zorunludur.

React.js:

Kurulum: npx astro add react -y.
Dikkat: Bileşen ismi ile export edilen isim aynı olmalıdır.

Svelte:

Kurulum: npx astro add svelte -y.

Alpine.js:

Kurulum: npx astro add alpinejs -y.
Farkı: Kendi dosya uzantısı yoktur, doğrudan HTML içinde x-data, x-show gibi direktiflerle çalışır.

Tailwind CSS:

Kurulum: npx astro add tailwind -y.
Utility class'ları (örn: class="bg-gray-800") doğrudan kullanabilirsiniz.

6. Gelişmiş Özellikler: Cookieler ve Querystring

Cookieler (Çerezler) ile Çalışma

Astro'da Astro.cookie modülü ile çerez okuma, yazma ve silme işlemleri yapılır.

Cookie Oluşturma:

Astro.cookie.set('isim', 'deger', { expires: 7, path: '/' });

*
Cookie Okuma: Astro.cookie.get('isim').

*
Cookie Silme: Astro.cookie.delete('isim').

*
Kontrol Etme: Astro.cookie.has('isim').

Querystring ve Middleware Kullanımı

URL parametrelerini (örneğin ?sayfa=2) okumak için SSR (Sunucu Tarafı Render) modu aktif edilmelidir (output: 'server' veya 'hybrid').

Middleware Oluşturma: src/middleware.ts dosyası oluşturun.

import { defineMiddleware } from "astro/middleware";
export const onRequest = defineMiddleware((context, next) => {
    let query = new URLSearchParams(context.url.search);
    context.locals.sayfa = Number(query.get('sayfa')) || 1;
    return next();
});

Tip Tanımlama (env.d.ts):

declare namespace App {
    interface Locals {
        sayfa: number;
    }
}

Sayfada Kullanım:

---
let sayfa = Astro.locals.sayfa;
---
<p>Şu anki sayfa: {sayfa}</p>