React Kullanımı

Bu belge, Falcon’da React’in neden eklendiğini, nasıl kurulduğunu ve ne zaman nasıl kullanılacağını anlatır.

Falcon öncelikle Astro ile çalışır. React, tüm siteyi React uygulamasına çevirmek için değil; yalnızca etkileşim gereken küçük parçalar için eklenmiştir.

---

Neden React?

Astro sayfaları varsayılan olarak statik HTML üretir: hızlı, SEO dostu, az JavaScript.
Bazı parçalar ise tarayıcıda durum (state) ve olay (event) ister:

İhtiyaç	Astro yeterli mi?	React gerekir mi?
Statik başlık, metin, layout	Evet	Hayır
<Button>, <Card> (Fix UI)	Evet (.astro)	Hayır
Tema aç/kapa (localStorage)	Zor / kırılgan	Evet
Carousel, sürükle-kaydır	Zor	Evet
Açılır menü, modal state	Kısmen (vanilla)	Genelde evet
Form doğrulama (canlı)	Kısmen	İhtiyaca göre

Özet: Görünüm Fix UI + Tailwind ile Astro’da kalır; tıklanınca değişen, hatırlayan, animasyonlu etkileşim React adasında (island) yazılır.

Bu yaklaşıma Islands Architecture denir: sayfanın çoğu HTML, etkileşimli kısımlar ayrı “adalar”.

---

Fix UI Ile İlişki

İki katman karıştırılmamalı:

Katman	Teknoloji	Örnek
Görünüm (stil)	Fix UI fix-* + token CSS	fix-btn, fix-card
Etkileşim (davranış)	React .tsx	ThemeToggle, carousel

React bileşeni içinde de fix-btn veya Tailwind kullanılabilir; buton/kart stilinin kaynağı yine src/styles/components/_fix-*.css olmalıdır. React’te uzun utility zinciriyle yeni bir “buton dili” icat etme.

---

Ne Yaptık? (Kurulum)

Paketler

npm install @astrojs/react react react-dom
npm install -D @types/react @types/react-dom

Paket	Görevi
@astrojs/react	Astro ↔ React köprüsü
react, react-dom	React 19 çalışma zamanı
@types/react, @types/react-dom	TypeScript tipleri

astro.config.mjs

import react from '@astrojs/react';

export default defineConfig({
  integrations: [react()],
  // … tailwindcss vite eklentisi aynı kalır
});

Bu satır olmadan .tsx dosyaları Astro tarafından işlenmez.

TypeScript

tsconfig.json içinde JSX için React modu tanımlı olmalı (jsx: react-jsx veya Astro şablonunun verdiği ayar). Yeni dosyalar .tsx uzantılı olur.

---

Nasıl Çalışır?

Sayfa (.astro) — statik HTML
    │
    ├── <Button />           ← Astro + Fix UI (JS yok)
    │
    └── <ThemeToggle client:load />  ← React island (JS var)
              │
              └── ThemeToggle.tsx

• .astro: Sunucuda render; varsayılan olarak tarayıcıya JS göndermez.
• .tsx: React bileşeni; yalnızca bir client:* direktifi ile sayfaya eklendiğinde JS yüklenir.

Performans için kural: React’i yalnızca gereken yerde, mümkün olan en hafif direktifle kullan.

---

client:* Direktifleri (Kısa)

Direktif	Ne zaman?
client:load	Sayfa açılır açılmaz çalışmalı (tema, kritik UI)
client:visible	Öğe görününce (carousel, aşağıdaki bloklar)
client:idle	Tarayıcı boşalınca
client:media="(...)"	Belirli breakpoint’te

Direktif yoksa React bileşeni render edilmez / etkileşim çalışmaz — bu bilinçli bir tasarruf.

---

Dosya Yapısı (Öneri)

src/components/
  ui/              ← Astro + Fix UI (Button.astro, Card.astro)
  i18n/            ← Astro (LanguageSwitcher.astro)
  islands/         ← React (.tsx) — tema, toast, form
    ThemeToggle.tsx
    Toaster.tsx
    FormSubmitToast.tsx

• Statik veya sadece HTML/CSS → .astro + ui/
• State / event → islands/*.tsx
• Dil değiştirici → i18n/LanguageSwitcher.astro (React değil)

---

Kullanım Örnekleri

1. React Bileşeni Oluştur

src/components/islands/ThemeToggle.tsx:

import { useState, useEffect } from 'react';

export default function ThemeToggle() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    document.documentElement.classList.toggle('dark', dark);
  }, [dark]);

  return (
    <button
      type="button"
      className="fix-btn fix-btn--outline fix-btn--s"
      onClick={() => setDark((d) => !d)}
      aria-pressed={dark}
    >
      {dark ? 'Açık' : 'Koyu'}
    </button>
  );
}

Stil: mevcut fix-btn sınıfları (Fix UI). Davranış: React.

2. Astro Sayfasında İsland Olarak Kullan

src/layouts/BaseLayout.astro veya Header.astro:

---
import ThemeToggle from '@/components/islands/ThemeToggle';
---

<header class="fix-container flex items-center justify-between">
  <slot name="logo" />
  <ThemeToggle client:load />
</header>

client:load — tema tercihi hemen uygulanabilsin diye.

3. Form Toast (Contact / Demo)

---
import FormSubmitToast from '@/components/islands/FormSubmitToast.tsx';
---

<form id="contact-form" class="fix-form" method="get" action="#">
  <!-- alanlar … -->
</form>
<FormSubmitToast client:load formId="contact-form" message={t(contactPage.toastSuccess, locale)} />

BaseLayout içinde global toast için Toaster.tsx (client:load) kullanılır. Ayrıntı: Formlar (Demo).

---

Ne Zaman React, Ne Zaman Astro?

Yap	Yapma
Tema toggle, modal state, carousel → React + client:*	Tüm sayfayı .tsx yap
Buton/kart görünümü → <Button>, fix-*	Her buton için ayrı React bileşeni
Layout, SEO, statik içerik → .astro	Astro’da useState taklidi (vanilla)
Island’ı islands/ altında topla	Her yerde client:load
Görünüm değişikliği → Fix UI CSS	React içinde yeni tasarım sistemi

---

Tailwind Ve site.css

React dosyaları da @source ile taranır (site.css içindeki components/** glob’u .tsx içerir). Island içinde className="flex gap-2" kullanabilirsin.

Fix UI bileşen stilleri yine _fix-*.css ve token’lardan gelir; React yalnızca hangi sınıfın hangi anda uygulandığını yönetir.

---

Performans Notları

• Varsayılan Astro = sıfıra yakın JS; React = yalnızca island kadar JS.
• Gereksiz client:load kullanma; mümkünse client:visible veya client:idle.
• Büyük kütüphaneleri tüm siteye değil, ilgili island’a import et.
• Fix UI statik kaldığı sürece buton/kartlar JS gerektirmez.

---

Falcon’da Mevcut İsland’lar

Dosya	Görev
islands/ThemeToggle.tsx	Karanlık mod (Header / layout’ta client:load)
islands/Toaster.tsx	Global Sonner toast (BaseLayout, client:load)
islands/FormSubmitToast.tsx	Contact ve demo formunda gönderim toast’ı

Astro (React değil): i18n/LanguageSwitcher.astro — dil seçimi sitePages üzerinden.

Testimonial carousel veya ayrı DocumentContent bileşeni yok; blog gövdesi render() + <Content /> ile Astro tarafında basılır.

Hepsi aynı kurala uyar: Astro sayfa + Fix UI stil + React yalnızca etkileşim.

---

Doğrulama

• npm run build hatasız.
• Yeni .tsx dosyası astro.config.mjs içinde react() ile tanımlı.
• Sayfada island kullanıyorsan client:* direktifi var.
• rg "\.tsx" src — yalnızca gerçekten etkileşim gereken dosyalar.

---

Özet Cümle

Falcon statik Astro + Fix UI ile render edilir; React yalnızca etkileşimli adalar için eklenir. Kurulum @astrojs/react + integrations: [react()]; kullanım islands/*.tsx + client:* direktifi; görünüm fix-type ve fix-btn ile Fix UI’da, davranış React’te kalır. Yazı rolleri: Yazı Stilleri.