Astro ile Modern Web Siteleri İnşa Etmek ve Üretime Almak: Sıfırdan Canlıya Adım Adım Rehber

Web geliştirme dünyası, performans odaklı yaklaşımın yeniden değer kazandığı bir dönemden geçiyor. Özellikle içerik ağırlıklı web sitelerinde, kullanıcılara tarayıcı tarafında minimum JavaScript yükü ile ulaşmak en kritik hedeflerden biri haline geldi. Bu bağlamda son yıllarda popülaritesi hızla artan Astro, sıfır JavaScript felsefesi (islands architecture) ile öne çıkıyor.

Bu yazıda, bir Astro projesinin geliştirme ortamından alınıp, üretim (production) ortamına taşınma sürecini; build adımlarını, optimizasyonları ve bir Linux sunucuda Nginx ile yayınlanma aşamalarını pratik bir bakış açısıyla ele alacağız.

1. Astro Projesine Genel Bakış ve Geliştirme Ortamı

Astro, özellikle içerik odaklı siteler (bloglar, dokümantasyonlar, kurumsal web siteleri) için tasarlandı. Bileşen tabanlı geliştirme yapısına izin vermesi, React, Vue veya Svelte gibi popüler kütüphaneleri aynı projede kullanabilmenizi sağlaması büyük bir esneklik sunar. Ancak projenin nihai çıktısı, tarayıcının doğrudan anlayabileceği saf HTML, CSS ve minimum düzeyde JavaScript dosyalarından oluşur.

Projenizi yerel makinenizde başlattığınızda genellikle şu komutu kullanırsınız:

npm run dev

Bu komut, geliştirme sunucusunu ayağa kaldırır ve dosya değişikliklerini anında tarayıcıya yansıtır (HMR - Hot Module Replacement). Ancak canlı ortama geçiş yapmadan önce projenin statik dosyalarını derlememiz gerekir.

2. Üretim İçin Build (Derleme) Süreci

Bir Astro projesini canlıya almadan önce yapılması gereken ilk şey, astro build komutunu çalıştırmaktır. Bu komut, projenizi tarayıcı için optimize edilmiş hale getirir ve genellikle kök dizin altında dist/ adında bir klasör oluşturur.

Projenizin package.json dosyasındaki script tanımları genellikle şu şekildedir:

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

Derleme işlemini başlatmak için:

npm run build

Bu komut çalıştırıldığında Astro, şunları yapar:

• Markdown veya MDX dosyalarınızı işler ve HTML’e dönüştürür.
• Sayfa bileşenlerini (components) derler.
• CSS dosyalarını küçültür (minify) ve optimize eder.
• Varsa statik varlıkları (görseller, fontlar) dist/ dizinine kopyalar.

astro.config.mjs Dosyasının Rolü

Build sürecini etkileyen en önemli faktörlerden biri konfigürasyon dosyasıdır. Özellikle sitenizin yayınlanacağı alan adı veya alt dizin (subpath) değişecekse site ve base parametrelerinin doğru ayarlanması gerekir.

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://www.canerserbest.com',
  // Eğer site kök dizinde değil de bir alt dizinde yayınlanacaksa:
  // base: '/blog',
});

Yanlış yapılandırılmış bir site URL’i, özellikle site haritası (sitemap) üretiminde ve mutlak bağlantıların (absolute paths) doğru çalışmasında sorunlara yol açabilir.

3. Üretim Çıktısının Sunucuya Aktarılması

Build işlemi başarıyla tamamlandıktan sonra elinizde tamamen statik dosyalardan oluşan bir dist/ klasörü bulunur. Bu aşamadan sonra bu dosyaları bir web sunucusuna (örneğin Ubuntu Server üzerinde çalışan Nginx) taşımanız gerekir.

Dosyaları sunucuya aktarmak için farklı yöntemler kullanabilirsiniz. En yaygın ve güvenli yöntemlerden biri rsync veya scp kullanmaktır.

Yerel makinenizden sunucuya dosya aktarımı için örnek bir komut:

rsync -avz --delete ./dist/ kullanici@sunucu_ip:/var/www/astro-site/dist/

Bu komut:

• -a: Dosya izinlerini ve yapısını korur.
• -v: İşlem detaylarını ekranda gösterir.
• -z: Aktarım sırasında sıkıştırma yapar.
• --delete: Sunucuda artık var olmayan eski dosyaların silinmesini sağlar.

4. Nginx ile Statik Dosya Sunumu

Astro projeleri statik çıktı ürettiği için arkasında bir Node.js süreci çalıştırmaya (özel SSR - Server Side Rendering senaryoları hariç) gerek yoktur. Bu durum, sunucu kaynak tüketimini minimuma indirir ve performansı maksimize eder. Dosyaları sunmak için Nginx en ideal tercihtir.

Nginx Blok Yapılandırması

Sunucunuzda /etc/nginx/sites-available/astro-site adında bir konfigürasyon dosyası oluşturun:

server {
    listen 80;
    server_name canerserbest.com www.canerserbest.com;

    root /var/www/astro-site/dist;
    index index.html;

    # Güvenlik başlıkları ve loglama
    access_log /var/log/nginx/astro_access.log;
    error_log /var/log/nginx/astro_error.log;

    location / {
        try_files $uri $uri/ =404;
    }

    # Statik varlıklar için önbellekleme (Caching)
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|webp)$ {
        expires 1y;
        add_header Cache-Control "public, no-transform";
    }
}

Bu yapılandırma:

• Gelen istekleri doğrudan Astro’nun build çıktısı olan /var/www/astro-site/dist dizinine yönlendirir.
• try_files direktifi ile SPA veya dosya yönlendirmelerinin doğru çalışmasını sağlar.
• Statik dosyalar için tarayıcı önbelleklemesini (browser caching) aktif hale getirerek sonraki yükleme sürelerini hızlandırır.

Konfigürasyonu test edin ve Nginx’i yeniden başlatın:

sudo nginx -t
sudo systemctl restart nginx

5. Sürekli Entegrasyon ve Dağıtım (CI/CD) Süreçleri

Manuel olarak npm run build alıp dosyaları sunucuya rsync ile göndermek küçük projeler için kabul edilebilir olsa da, ölçeklenebilir bir yapıda bu sürecin otomatikleştirilmesi gerekir. GitHub Actions kullanarak her main dalına (branch) yapılan push işleminde sitenizin otomatik olarak derlenmesini ve sunucuya gönderilmesini sağlayabilirsiniz.

Örnek bir GitHub Actions iş akışı (.github/workflows/deploy.yml):

name: Deploy Astro Site

on:
  push:
    branches: [ "main" ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Deploy to Server
        uses: easingthemes/ssh-deploy@v5
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
          ARGS: "-rltgoDzvO --delete"
          SOURCE: "dist/"
          REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
          REMOTE_USER: ${{ secrets.REMOTE_USER }}
          TARGET: "/var/www/astro-site/dist/"

Bu otomasyon sayesinde kodunuzu GitHub’a gönderdiğiniz anda test edilir, derlenir ve doğrudan canlı sunucunuza aktarılır.

Sonuç

Astro, modern web geliştirme standartlarını karşılarken donanım kaynaklarını en verimli şekilde kullanan araçlardan biridir. Doğru bir build süreci ve Nginx gibi güçlü bir web sunucusu ile birleştiğinde, son derece hızlı ve dayanıklı web siteleri elde edebilirsiniz. Süreci manuel adımlardan kurtarıp CI/CD boru hatlarına (pipelines) taşımak ise uzun vadede sürdürülebilir bir operasyonun anahtarıdır.

---

Bu yazı Gemini ile otomatik oluşturulmuştur.