jskelet 0.1.1

package/docs/10-dagitim.md

@@ -0,0 +1,329 @@
+# 10 — Dağıtım
+
+Bu belge bir JSkelet uygulamasını yayına almayı anlatır: prod build ve start
+akışı, ayarlanması gereken ortam değişkenleri, çalışan bir Docker kurulumu, ters
+proxy ve `trust proxy` notları, sağlık kontrolü ucunun nasıl eklendiği ve
+ölçekleme sırasında önbelleğin nasıl davrandığı. Build adımlarının içeriği
+[08-build.md](./08-build.md)'de, önbellek davranışı [06-cache.md](./06-cache.md)'de.
+
+## Prod akışı
+
+```bash
+npm ci
+npm run build     # jskelet build
+npm start         # jskelet start
+```
+
+`jskelet build` `NODE_ENV` verilmemişse `production` ayarlar ve tüm adımları
+çalıştırır: fontlar, ikon sprite, CSS, client JS, görseller, manifest,
+precompress.
+
+`jskelet start` önce `.jskelet/manifest.json` dosyasına bakar; yoksa build'i
+kendisi çalıştırır. Docker imajında build zaten yapıldığı için bu bir no-op;
+amaç `npm start`ı doğrudan çalıştıran birinin stilsiz bir sayfayla
+karşılaşmaması.
+
+Sunucu hazır olduğunda tek satır basar:
+
+```
+jskelet → http://localhost:3000 (production)
+```
+
+Süreç iki güvenlik ağıyla korunur: `unhandledRejection` ve `uncaughtException`
+loglanır ve süreç ayakta kalır. Bir haber sitesinde tek sayfanın hatası tüm
+siteyi indirmemeli. Kendi hata izleme aracınıza (Sentry vb.) bağlanmak
+istiyorsanız aynı olaylara kendi dinleyicinizi de ekleyebilirsiniz.
+
+## Ortam değişkenleri
+
+Zorunlu hiçbir değişken yok; hepsinin makul bir varsayılanı var. Prod'da
+ayarlamayı düşünmeniz gerekenler:
+
+| Değişken | Öneri | Neden |
+| --- | --- | --- |
+| `NODE_ENV` | `production` | Şablon cache'i, manifest'in bir kez okunması, bozuk route modülünde fırlatma |
+| `PORT` | `3000` | Orkestratörünüzün beklediği port |
+| `HOST` | `0.0.0.0` | Kapsayıcı içinde dışarıdan erişim için (varsayılan) |
+| `PREWARM_MAX` | Site boyutuna göre | Açılışta ısıtılacak sayfa sayısı |
+| `PREWARM_INTERVAL_SECONDS` | `0` ya da uzun bir değer | Hiç ziyaret edilmeyen sayfaları sıcak tutmak isterseniz |
+| `DEV_TOKEN` | Yalnızca staging'de | Yayına açılmamış ortamı gizler |
+
+Tam liste ve prewarm ayarlarının öncelik sırası:
+[07-yapilandirma.md](./07-yapilandirma.md).
+
+CLI `--env-file-if-exists=.env` ile çalıştığı için `.env` dosyası varsa otomatik
+yüklenir; yoksa hata verilmez. Kapsayıcıda genelde bu dosya yerine ortam
+değişkenleri doğrudan enjekte edilir. İki kaynağı birlikte kullanmak hangi
+değerin geçerli olduğunu belirsizleştirir; prod imajında `.env` bulundurmamak en
+temizidir.
+
+**Gizli anahtarlar `clientEnv` listesine konmamalıdır:** oradaki değerler client
+bundle'a düz metin olarak gömülür ([08-build.md](./08-build.md)).
+
+## Docker
+
+Çok aşamalı bir imaj: build aşaması dev bağımlılıklarıyla derler, çalışma
+aşaması yalnızca üretim bağımlılıklarını ve build çıktısını taşır.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
+# ---------- build ----------
+FROM node:22-bookworm-slim AS build
+WORKDIR /app
+
+# Bağımlılıklar ayrı katmanda: kaynak değişince yeniden kurulum yapılmasın.
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# `public/fonts/` commit edilmiş olmalı: build'in ağa çıkması gerekmesin.
+COPY . .
+
+ENV NODE_ENV=production
+RUN npx jskelet build
+
+# ---------- runtime ----------
+FROM node:22-bookworm-slim AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOST=0.0.0.0
+
+COPY package.json package-lock.json ./
+# sharp ve tailwind yalnızca build zamanı gerekli; çalışma imajına girmesin.
+RUN npm ci --omit=dev && npm cache clean --force
+
+COPY --from=build /app/jskelet.config.mjs ./jskelet.config.mjs
+COPY --from=build /app/jsconfig.json ./jsconfig.json
+COPY --from=build /app/routes ./routes
+COPY --from=build /app/views ./views
+COPY --from=build /app/lib ./lib
+COPY --from=build /app/public ./public
+COPY --from=build /app/.jskelet ./.jskelet
+
+# Root olmayan kullanıcı.
+USER node
+
+EXPOSE 3000
+
+# Sağlık kontrolü: aşağıdaki route'u eklediğinizi varsayar.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/api/healthcheck').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["npx", "jskelet", "start"]
+```
+
+Notlar:
+
+- **`client/` ve `styles/` çalışma imajına gerekmez:** çıktıları
+  `public/assets/` altında. `views/` ve `routes/` gerekir, çünkü render çalışma
+  anında yapılıyor. `lib/` yalnızca projenizde varsa kopyalayın.
+- **`.jskelet/` gerekir:** `manifest.json` olmadan `asset()` hash'li URL'leri
+  bulamaz ve `jskelet start` build'i baştan çalıştırmaya kalkar.
+- **`sharp` çalışma imajında gerekmez:** yalnızca build zamanı görsel
+  optimizasyonu için. `--omit=dev` ile dışarıda kalır (devDependency olarak
+  kurulmuşsa).
+- `jskelet start`ı `npx` olmadan çağırmak isterseniz
+  `CMD ["node", "node_modules/jskelet/bin/jskelet.mjs", "start"]` de çalışır.
+
+`.dockerignore`:
+
+```
+node_modules
+.git
+.jskelet
+public/assets
+.env
+```
+
+Build aşaması `npx jskelet build` ile bunları kendisi üretir.
+
+### Depo alt dizininden dağıtım
+
+Bu depodaki örnekler jskelet'i npm'den değil `"jskelet": "file:../.."` ile
+alıyor. Coolify, Railway, Render gibi araçlarda "base directory" olarak
+`examples/marketing` verilirse build context yalnızca o dizin olur, `../..`
+context'in dışında kalır ve kurulum `npm ci`de düşer. Doğru ayar: **base
+directory `/`**, Dockerfile konumu `/examples/marketing/Dockerfile`. Çalışan
+örnek `examples/marketing/Dockerfile` içinde ve context'i depo kökü kabul eder:
+
+```bash
+docker build -f examples/marketing/Dockerfile -t jskelet-marketing .
+docker run --rm -p 3000:3000 -e SITE_URL=https://example.com jskelet-marketing
+```
+
+Kendi uygulamanızda jskelet normal bir bağımlılık olacağı için bu kısıt yoktur;
+yukarıdaki çok aşamalı imaj yeterli.
+
+## Sağlık kontrolü
+
+Framework hazır bir sağlık kontrolü ucu **eklemez**; kendi route'unuza koymanız
+gerekir. Varsayılan `devGateBypass` listesi `/api/healthcheck` yolunu içerdiği
+için bu adı kullanmak en az sürprizli seçenektir: `DEV_TOKEN` ayarlı bir ortamda
+bile erişilebilir kalır.
+
+```js
+// routes/00-health.mjs
+import { getHtmlCacheSize } from "jskelet";
+
+export default function register(app) {
+  app.get("/api/healthcheck", (req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    res.json({
+      ok: true,
+      uptime: process.uptime(),
+      cache: getHtmlCacheSize(),
+    });
+  });
+}
+```
+
+Dosya adındaki `00-` öneki, bu route'un herhangi bir yakalayıcıdan önce
+kaydedilmesini sağlar ([03-routing.md](./03-routing.md)).
+
+Farklı bir yol kullanacaksanız `devGateBypass` listesini güncelleyin, aksi hâlde
+staging'de orkestratör 404 görür:
+
+```js
+devGateBypass: ["/healthz", "/robots.txt", "/sitemap.xml", "/favicon.ico"]
+```
+
+Isıtma turu sağlık kontrolünü etkilemez: prewarm başarısız olsa bile süreç ayakta
+kalır ve sayfalar (soğuk da olsa) servis edilir.
+
+Hazırlık (readiness) ile canlılık (liveness) ayrımı gerekiyorsa ısıtmanın
+durumunu de raporlayabilirsiniz:
+
+```js
+import { prewarmProgress } from "jskelet";
+
+app.get("/api/ready", (req, res) => {
+  const warmedUp = !prewarmProgress.active && prewarmProgress.finishedAt !== null;
+  res.status(warmedUp ? 200 : 503).json({ warmedUp, ...prewarmProgress });
+});
+```
+
+Bu ucun yolunu `prewarmSkip` ile ısıtma dışında bırakmayı unutmayın (varsayılan
+`/api/` öneki zaten kapsıyor).
+
+## Ters proxy
+
+Express uygulaması `trust proxy`yi **açık** olarak kurar (`app.set("trust proxy", true)`).
+Bunun sonuçları:
+
+- `req.protocol` `X-Forwarded-Proto` başlığından okunur, yani proxy TLS'i
+  sonlandırıyorsa `https` doğru döner.
+- `req.ip` `X-Forwarded-For` zincirinden çözülür.
+- `res.redirect()` ile üretilen mutlak URL'ler doğru şemayı taşır.
+
+Bu ayar **proxy'nin bu başlıkları güvenilir biçimde yazdığını varsayar.**
+Uygulamayı doğrudan internete açacaksanız istemcinin `X-Forwarded-*` başlıklarını
+uydurabileceğini unutmayın; her zaman bir proxy ya da yük dengeleyici arkasında
+çalıştırın ve proxy'nin gelen `X-Forwarded-For` başlığını üzerine yazdığından
+emin olun.
+
+Örnek nginx yapılandırması:
+
+```nginx
+upstream jskelet {
+  server 127.0.0.1:3000;
+  keepalive 32;
+}
+
+server {
+  listen 443 ssl http2;
+  server_name ornek.com;
+
+  # Yanıt gövdeleri zaten sıkıştırılmış geliyor; ikinci kez sıkıştırma yapma.
+  gzip off;
+
+  location / {
+    proxy_pass http://jskelet;
+    proxy_http_version 1.1;
+
+    proxy_set_header Host              $host;
+    proxy_set_header X-Real-IP         $remote_addr;
+    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Connection        "";
+
+    # Sıkıştırılmış yanıt alabilmek için upstream'e ilet.
+    proxy_set_header Accept-Encoding   $http_accept_encoding;
+  }
+}
+```
+
+Önemli noktalar:
+
+- **Sıkıştırmayı iki kez yapmayın.** JSkelet brotli/gzip pazarlığını kendisi
+  yapıyor ve önbelleklenmiş sayfalarda sıkıştırılmış gövdeyi saklıyor. nginx'in
+  kendi `gzip`ini açık bırakmak brotli'yi çözüp yeniden gzip'lemeye yol açabilir.
+- **`Accept-Encoding`i iletin**, yoksa uygulama sıkıştırma yapmaz ve önbellekteki
+  hazır sıkıştırılmış gövdeler kullanılmaz.
+- `Vary: Accept-Encoding` uygulama tarafından yazılır; proxy önbelleği bunu
+  dikkate alır.
+
+### CDN ile birlikte
+
+Önbelleklenebilir sayfalara yazılan başlık:
+
+```
+Cache-Control: public, max-age=0, s-maxage=<revalidate>, stale-while-revalidate=60
+```
+
+`max-age=0` tarayıcıda saklamayı kapatır, `s-maxage` CDN'e süreyi bildirir. Yani
+aynı tazelik modeli iki katmanda birlikte çalışır: CDN `s-maxage` boyunca kendi
+kopyasını verir, süresi geçtiğinde origin'e sorar ve origin de kendi
+önbelleğinden anında yanıtlar.
+
+`X-JSkelet-Cache` başlığı hangi katmanın yanıtladığını teşhis etmeyi
+kolaylaştırır; CDN'in kendi cache başlığıyla birlikte okuyun
+([06-cache.md](./06-cache.md)).
+
+Statik varlıklar (`/assets/`, `/fonts/`) `immutable` işaretli olduğu için CDN'de
+süresiz tutulabilir; hash değiştiğinde URL de değişir.
+
+## Ölçekleme
+
+HTML önbelleği **süreç belleğinde** yaşar. Birden fazla kopya çalıştırdığınızda:
+
+- Her kopyanın kendi önbelleği olur; bellek kullanımı kopya sayısıyla çarpılır
+  (en fazla 500 girdi + sıkıştırılmış kopyaları).
+- Her kopya açılışta kendi ısıtma turunu yapar. `PREWARM_MAX` ve
+  `PREWARM_CONCURRENCY` değerlerini upstream API'nizin kopya sayısıyla çarpılmış
+  yükü kaldırabileceği şekilde ayarlayın.
+- `clearHtmlCache()` yalnızca çağrıldığı süreci etkiler. Tüm kopyaları
+  temizlemek gerekiyorsa bunu orkestratör düzeyinde (yeniden başlatma) ya da
+  kendi yazacağınız bir yayın mekanizmasıyla çözmeniz gerekir.
+- Önünde bir CDN varsa çoğu istek origin'e hiç gelmez ve kopya başına önbellek
+  farkı görünmez hâle gelir.
+
+Tek kopyanın kapasitesini artırmak için `revalidate` sürelerini yükseltmek,
+kopya eklemekten genellikle daha etkilidir: önbellek isabet oranı arttıkça
+istek başına iş neredeyse sıfıra iner.
+
+## Yayın öncesi kontrol listesi
+
+- [ ] `NODE_ENV=production`
+- [ ] `npm run build` çalıştı ve `.jskelet/manifest.json` üretildi
+- [ ] `public/fonts/` içindeki woff2 dosyaları commit edilmiş
+      ([08-build.md](./08-build.md))
+- [ ] `styles/globals.css` içindeki `@source` direktifleri tüm şablon
+      dizinlerini kapsıyor
+- [ ] `hooks.notFound()` tanımlı ve 404 şablonu var
+- [ ] `hooks.metadata()` içinde `siteUrl` var (göreli `canonical`lar
+      mutlaklaşsın)
+- [ ] `cache().html` desenleri sitenin tazelik profiline uygun
+- [ ] `hooks.prewarmPaths()` en önemli sayfaları başa koyuyor
+- [ ] `headers()` içinde CSP ve güvenlik başlıkları tanımlı
+- [ ] Sağlık kontrolü ucu var ve `devGateBypass` listesinde
+- [ ] Staging'de `DEV_TOKEN` ayarlı, prod'da **ayarlı değil**
+- [ ] Ters proxy `Accept-Encoding`i iletiyor ve kendi sıkıştırmasını yapmıyor
+- [ ] `clientEnv` listesinde gizli anahtar yok
+
+## Sırada ne var
+
+- Önbellek ayarları ve prewarm: [06-cache.md](./06-cache.md)
+- Ortam değişkenlerinin tamamı: [07-yapilandirma.md](./07-yapilandirma.md)
+- Next.js'ten taşıma: [11-tasima.md](./11-tasima.md)

package/docs/11-tasima.md

@@ -0,0 +1,352 @@
+# 11 — Next.js'ten taşıma
+
+Bu belge Next.js App Router kullanan bir projeyi JSkelet'e taşımayı anlatır:
+kavram ve API karşılıklarının tablosu, taşınamayan şeylerin açıkça listesi ve
+adım adım bir plan. JSkelet'in yüzeyi bilinçli olarak Next'in fiilen kullanılan
+alt kümesine benzetildi — `next.config` sözdizimi, Metadata API, `notFound()`,
+`revalidate`, `cache()` gibi kavramlar tanıdık gelecek. Farkların *nedenleri*
+[02-mimari.md](./02-mimari.md)'de.
+
+## Karşılık tablosu
+
+### Yapılandırma
+
+| Next.js | JSkelet | Not |
+| --- | --- | --- |
+| `next.config.mjs` | `jskelet.config.mjs` | Aynı ruh, daha küçük yüzey ([07](./07-yapilandirma.md)) |
+| `headers()` | `headers()` | Aynı şekil: `{ source, headers: [{ key, value }] }` |
+| `redirects()` | `redirects()` | `permanent` → 308, aksi hâlde 307; `statusCode` ile ezilebilir |
+| `rewrites()` | `rewrites()` | `beforeFiles` / `afterFiles` fazları var; `fallback` yok |
+| `compress: true` | Otomatik | `node:zlib` ile brotli + gzip |
+| `images.deviceSizes` | `images.widths` | Build zamanı webp üretimi ([08](./08-build.md)) |
+| `NEXT_PUBLIC_*` | `clientEnv: [...]` | Hangi anahtarın açık olduğu isimden değil config'ten belli |
+| `experimental.*` | — | Yok |
+
+### Routing ve render
+
+| Next.js | JSkelet | Not |
+| --- | --- | --- |
+| `app/page.js` (dosya bazlı routing) | `routes/*.mjs` içinde `app.get(...)` | Sıra açık yazılır ([03](./03-routing.md)) |
+| `app/[slug]/page.js` | `app.get("/:slug", route(...))` | Express desen sözdizimi |
+| `params`, `searchParams` | `ctx.params`, `ctx.query` | Controller'ın tek argümanı |
+| `layout.js` | `views/layout.ejs` + `hooks.layoutContext()` | Tek layout; iç içe layout yok |
+| Sunucu bileşeni (RSC) | Controller + EJS şablonu + `views/components/**` | Fonksiyon HTML string döndürür |
+| İstemci bileşeni (`"use client"`) | Island (`data-island` + `mount`) | Sayfanın tamamı hidre edilmez ([05](./05-islands.md)) |
+| `notFound()` | `notFound()` | Aynı ad, aynı kontrol akışı |
+| `redirect()` | `redirect()` (307) | Kalıcı için `permanentRedirect()` (308) |
+| `not-found.js` | `hooks.notFound()` | Bir sayfa tanımı döndürür |
+| `error.js` | Express hata yöneticisi | Framework 500 için minimal HTML döner |
+| `loading.js` / Suspense | — | Sunucu HTML'i tam; iskelet gerekmiyor |
+| Streaming SSR | — | Yanıt tek parça |
+| `generateMetadata()` | Controller `metadata` + `hooks.metadata()` | Aynı alan adları ([04](./04-render-ve-sablonlar.md)) |
+| `generateStaticParams()` | `hooks.prewarmPaths()` | Build zamanı değil, açılış zamanı ısıtma |
+| Route Handlers (`route.js`) | Düz Express handler'ı | `app.get/post(...)` |
+| Middleware (`middleware.ts`) | Express middleware + config `rewrites`/`headers`/`redirects` | `app.use(...)` |
+
+### Veri ve önbellek
+
+| Next.js | JSkelet | Not |
+| --- | --- | --- |
+| `export const revalidate = 60` | `route(controller, { revalidate: 60 })` | Ya da `cache().html` ([06](./06-cache.md)) |
+| ISR (dosyaya yazılan prerender) | Bellek içi TTL cache + stale-while-revalidate | Diske yazılmaz |
+| `fetch(..., { next: { revalidate } })` | — | Önbellek sayfa düzeyinde |
+| `unstable_cache` | — | İstek üstü veri önbelleği yok; sayfa önbelleği var |
+| React `cache()` | `cache()` | Aynı davranış: istek içi memoizasyon |
+| `revalidatePath()` | `clearHtmlCache()` | Şu anda tek tek anahtar geçersizleme yok |
+| `cookies()`, `headers()` | `ctx.req.headers`, `ctx.req.cookies`* | Express nesnesine doğrudan erişim |
+| `dynamic = "force-dynamic"` | `revalidate` vermemek | Önbellek kapalı demek |
+
+\* Express 5 çerezleri kendiliğinden ayrıştırmaz; `cookie-parser` ekleyin ya da
+başlığı elle okuyun.
+
+### Bileşenler ve yardımcılar
+
+| Next.js | JSkelet | Not |
+| --- | --- | --- |
+| `next/link` | `link({ href, text })` — `jskelet/tags` | `title` otomatik, dış bağlantıya `rel`/`target` otomatik |
+| `next/link` prefetch'i | `navigation: { prefetch, prerender }` | Speculation Rules; client runtime'ı yok ([07](./07-yapilandirma.md)) |
+| `next/image` | `image({ src, alt, priority })` — `jskelet/tags` | `srcset` build manifest'inden |
+| `next/font/google` | `fonts: [{ family, weights }]` | Self-host woff2, commit edilir |
+| `@phosphor-icons/react` | `icon({ name, weight })` — `jskelet/tags` | Build zamanı SVG sprite |
+| `react-dom` preconnect/preload | `preconnect: [...]` + `headHints()` | ([04](./04-render-ve-sablonlar.md)) |
+| `clsx` | `cx()` — `jskelet/html` | — |
+| `cn()` (clsx + tailwind-merge) | `cn()` — `jskelet/html` | Aynı davranış |
+| JSX otomatik kaçışı | `esc()` — `jskelet/html` | **Elle çağırmanız gerekir** |
+| React Context | `createStore()` — `jskelet/client` | Minimal pub/sub |
+| `useState` / `useEffect` | Island `mount()` içinde düz JS | — |
+| `useSyncExternalStore` | `store.subscribe()` | — |
+| `<Script>` | Layout'ta `<script>` ya da island | — |
+
+### Neyin karşılığı yok
+
+Bunları taşıma planında baştan hesaba katın:
+
+- **React'in kendisi.** Bileşenler HTML string döndüren fonksiyonlara dönüşür.
+  JSX yok, hook yok, sanal DOM yok.
+- **TypeScript.** Proje düz JS + JSDoc. `jsconfig.json` içinde `checkJs: true`
+  ile editörden tip kontrolü alırsınız.
+- **İç içe layout'lar.** Tek bir layout var; ortak bölümleri EJS `include` ya da
+  bileşen fonksiyonlarıyla paylaşırsınız.
+- **Streaming / Suspense / kısmi prerender.** Yanıt tek parça üretilir.
+- **İstemci tarafı yönlendirme.** Gezinme gerçek sayfa yüklemesidir. Sunucu HTML'i
+  önbellekten geldiği için pratikte çok hızlıdır, ama SPA geçişleri yoktur.
+  Aradaki farkı kapatan şey `navigation` bölümü: prefetch/prerender tıklamadan
+  önce belgeyi hazırlar, `viewTransition` geçişi yumuşatır
+  ([07](./07-yapilandirma.md)).
+- **Server Actions.** Form gönderimleri normal `app.post(...)` handler'larıdır.
+- **Tek tek yol geçersizleme (`revalidatePath`).** Şimdilik tüm önbelleği
+  temizlemek (`clearHtmlCache()`) ya da TTL'in dolmasını beklemek var.
+- **Otomatik görsel optimizasyonu (istek anında).** Optimizasyon build zamanında
+  yapılır ve yalnızca `public/` altındaki yerel görselleri kapsar; uzak görseller
+  olduğu gibi basılır.
+
+## Yan yana örnek
+
+**Next.js (App Router):**
+
+```jsx
+// app/haber/[slug]/page.jsx
+import { notFound } from "next/navigation";
+import Image from "next/image";
+import { getArticle } from "@/lib/api";
+
+export const revalidate = 300;
+
+export async function generateMetadata({ params }) {
+  const article = await getArticle(params.slug);
+  return {
+    title: article?.title,
+    description: article?.summary,
+    alternates: { canonical: `/haber/${params.slug}` },
+  };
+}
+
+export default async function Page({ params }) {
+  const article = await getArticle(params.slug);
+  if (!article) notFound();
+
+  return (
+    <article className="wrapper">
+      <h1 className="text-3xl font-bold">{article.title}</h1>
+      <Image src={article.cover} alt={article.title} priority width={1200} height={630} />
+      <div dangerouslySetInnerHTML={{ __html: article.body }} />
+    </article>
+  );
+}
+```
+
+**JSkelet:**
+
+```js
+// routes/50-haber.mjs
+import { getArticle } from "@/lib/api.js";
+
+export default function register(app, { route, notFound }) {
+  app.get(
+    "/haber/:slug",
+    route(
+      async ({ params }) => {
+        const article = await getArticle(params.slug);
+        if (!article) notFound();
+
+        return {
+          view: "pages/article",
+          data: { article },
+          metadata: {
+            title: article.title,
+            description: article.summary,
+            canonical: `/haber/${params.slug}`,
+            openGraph: { type: "article", image: article.cover },
+          },
+        };
+      },
+      { revalidate: 300 },
+    ),
+  );
+}
+```
+
+```ejs
+<%# views/pages/article.ejs %>
+<article class="wrapper">
+  <h1 class="text-3xl font-bold"><%= article.title %></h1>
+  <%- image({ src: article.cover, alt: article.title, priority: true, width: 1200, height: 630 }) %>
+  <div><%- article.body %></div>
+</article>
+```
+
+`getArticle`'ın `cache()` ile sarılması, aynı render'da `hooks.layoutContext()`
+de aynı yazıyı isterse tek upstream isteği yapılmasını sağlar
+([06-cache.md](./06-cache.md)).
+
+## Adım adım plan
+
+### 1. İskeleti kur (yarım gün)
+
+Yeni bir dizinde `npx jskelet init` çalıştırın ve `jskelet dev`in açıldığını
+görün. Mevcut Next projesini olduğu gibi bırakın; taşıma paralel yürüsün.
+
+`jsconfig.json` içindeki `paths` alias'larınızı taşıyın — `@/` gibi önekler hem
+sunucuda hem bundle'da aynı şekilde çalışır ([02-mimari.md](./02-mimari.md)).
+
+### 2. `next.config.mjs`'i çevir (1-2 saat)
+
+`headers()`, `redirects()` ve `rewrites()` bölümleri neredeyse birebir kopyalanır.
+Desen sözdizimini kontrol edin: JSkelet `:slug`, `:path*`, `/a-:b` ve
+`/:path*.svg` biçimlerini destekler; daha karmaşık `path-to-regexp` ifadeleri
+desteklenmez ve uyarı üretir ([07-yapilandirma.md](./07-yapilandirma.md)).
+
+`NEXT_PUBLIC_*` değişkenlerini `clientEnv` listesine taşıyın ve adlarını
+sadeleştirin (ön ek artık anlam taşımıyor).
+
+### 3. Veri katmanını taşı (en kolay adım)
+
+`lib/` altındaki API istemcisi ve veri fonksiyonları genelde React'e bağımlı
+değildir; olduğu gibi kopyalanır. İki değişiklik yapın:
+
+- React `cache()` yerine `import { cache } from "jskelet"`.
+- Başarısız upstream yanıtlarında `reportUpstreamFailure({ status, path })`
+  çağırın. Bu, eksik veriyle üretilmiş sayfaların önbelleğe yazılmasını önler
+  ([06-cache.md](./06-cache.md)).
+
+### 4. Layout'u kur (yarım gün)
+
+`app/layout.jsx`'i `views/layout.ejs`'e çevirin. Framework'ün varsayılan
+layout'unu (`node_modules/jskelet/src/templates/layout.ejs`) kopyalayıp
+üzerine yazmak en hızlı yol.
+
+`layout.jsx` içinde veri çekiyorsanız (navigasyon, site ayarları) bunu
+`hooks.layoutContext()` içine taşıyın: gövde render'ıyla paralel çalışır ve
+döndürdüğü her alan layout local'i olur.
+
+Global metadata varsayılanlarını (`titleTemplate`, `siteUrl`, `description`)
+`hooks.metadata()` içine koyun.
+
+### 5. Bileşenleri çevir (en uzun adım)
+
+Her React bileşeni bir fonksiyona dönüşür:
+
+```jsx
+// Önce
+export function Badge({ label, tone = "neutral", className }) {
+  return <span className={cn("rounded px-2 py-1", TONES[tone], className)}>{label}</span>;
+}
+```
+
+```js
+// Sonra — views/components/badge.js
+import { attrs, cn, esc } from "jskelet/html";
+
+export function badge({ label, tone = "neutral", class: className }) {
+  return `<span${attrs({ class: cn("rounded px-2 py-1", TONES[tone], className) })}>${esc(label)}</span>`;
+}
+```
+
+Dikkat edilecekler:
+
+- **Kaçış artık elinizde.** JSX otomatik kaçıyordu; burada dış veriyi basarken
+  `esc()` çağırmak zorundasınız.
+- **`className` → `class`.** JS'te `class` ayrılmış sözcük olduğu için props'ta
+  `class: className` biçiminde yeniden adlandırın.
+- **Children yerine `html` alanı.** İç içe içerik string olarak geçirilir.
+- Named export olarak `views/components/**` altına koyduğunuz her fonksiyon
+  şablonlarda import gerektirmeden kullanılabilir
+  ([04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)).
+
+Bileşenleri küçük ve saf tutun; veri çekmeyi controller'da bırakın.
+
+### 6. Sayfaları taşı (sayfa başına saatler)
+
+Her `page.jsx` bir controller + bir EJS şablonuna bölünür. Sırayı düşünerek
+dosyalayın:
+
+```
+routes/
+├── 00-health.mjs        sağlık kontrolü
+├── 10-pages.mjs         sabit yollar: /, /hakkinda
+├── 50-haber.mjs         /haber/:slug
+└── 99-catch-all.mjs     /:slug  (varsa, en sonda)
+```
+
+`generateStaticParams()` kullandığınız yerler `hooks.prewarmPaths()`e dönüşür.
+Sitemap üreten fonksiyonunuz varsa aynısını kullanın.
+
+`export const revalidate` değerlerini ya `route()`un ikinci argümanına ya da tek
+bir yerden yönetmek için `cache().html` desenlerine taşıyın.
+
+### 7. İstemci bileşenlerini island'a çevir (sayfa başına saatler)
+
+Her `"use client"` bileşeni bir island olur. Süreç:
+
+1. Bileşenin **statik** çıktısını sunucu şablonuna taşıyın. İlk render'da
+   görünen her şey HTML'de olmalı.
+2. Kalan davranışı `mount(element, props)` içine yazın: `useState` yerel
+   değişken, `useEffect` doğrudan çağrı, event handler'lar `on()`/`onClick()`.
+3. Props'u `data-island-props` ile JSON olarak geçirin.
+4. Entry'de `registerAll()` haritasına ekleyin.
+5. Bağlanma stratejisini seçin: varsayılan (görünürlük), `data-island-eager`
+   (global davranış) ya da `data-island-idle` (ağır ve kritik olmayan).
+
+Context kullanan bileşenler için `createStore()` en yakın karşılık
+([05-islands.md](./05-islands.md)).
+
+**Bu adımın en büyük kazancı burada:** hidre edilen alan sayfanın tamamı değil,
+yalnızca gerçekten etkileşimli parçalar.
+
+### 8. CSS'i taşı (1-2 saat)
+
+Tailwind yapılandırmanız v4 formatındaysa `styles/globals.css` neredeyse aynı
+kalır. Tek kritik ekleme `@source` direktifleri:
+
+```css
+@import "tailwindcss" source(none);
+
+@source "../views";
+@source "../client";
+@source "../routes";
+@source "../lib";
+```
+
+Bunlar olmadan şablonlarda geçen sınıflar (özellikle
+`data-[state=open]:…` gibi varyantlar) sessizce düşer
+([08-build.md](./08-build.md)).
+
+`next/font` kullanıyorsanız `fonts: [{ family, weights }]` ekleyin ve
+`@font-face` bloklarını elle yazın; üretilen dosyalar `public/fonts/` altında
+sabit isimlerle durur.
+
+### 9. Doğrula ve ölç
+
+- `jskelet dev` ile gezip dev overlay'inde hata olmadığını doğrulayın.
+- Rapor sayfasında (`/__jskelet/dev/report`) her sayfanın Web Vitals ölçümlerine,
+  SSR boyutuna ve island durumuna bakın ([09-dev-araclari.md](./09-dev-araclari.md)).
+- Eksik ikon uyarılarını temizleyin.
+- `jskelet build` çıktısındaki boyutları eski Next bundle'ıyla karşılaştırın.
+- `X-JSkelet-Cache` başlığının beklediğiniz sayfalarda `HIT` döndüğünü kontrol
+  edin.
+
+### 10. Yayına al
+
+[10-dagitim.md](./10-dagitim.md) içindeki kontrol listesini geçin. Eski Next
+kurulumunu bir süre yanında tutup trafiği kademeli çevirmek, özellikle
+redirect kurallarının doğruluğunu ölçmek için işe yarar.
+
+## Taşıma sırasında sık yapılan hatalar
+
+- **`esc()` unutmak.** JSX'ten gelen alışkanlıkla `${value}` yazmak XSS demektir.
+  Şablonlarda `<%= %>` (kaçışlı) ile `<%- %>` (ham) ayrımına dikkat edin.
+- **`@source` eklemeden yeni bir dizin açmak.** Sınıflar sessizce düşer.
+- **Yakalayıcı route'u yanlış sıraya koymak.** `/:slug` her zaman en sonda.
+- **Sayfanın tamamını island yapmak.** Kazanç sunucu HTML'inin tam olmasından
+  geliyor; island'ı yalnızca gerçekten etkileşimli parçaya bağlayın.
+- **`revalidate` vermeyi unutmak.** Önbellek kapalı kalır, her istek render
+  edilir ve `X-JSkelet-Cache: MISS` döner.
+- **`reportUpstreamFailure()` çağırmamak.** Upstream düştüğünde eksik veriyle
+  üretilen sayfa tüm TTL boyunca servis edilir.
+- **`clientEnv`e gizli anahtar koymak.** Değerler bundle'da düz metin durur.
+
+## Sırada ne var
+
+- Mimari kararların gerekçeleri: [02-mimari.md](./02-mimari.md)
+- Island modelinin ayrıntıları: [05-islands.md](./05-islands.md)
+- Yapılandırma referansı: [07-yapilandirma.md](./07-yapilandirma.md)