SSR Framework'ler

Not

SSR geliştirme sürecinde hâlâ erken aşamalarda ve bazı yüzeyler ve davranışlar değişebilir.

LentyStyle framework başına adapter paketi dağıtmaz. Her framework entegrasyonu aynı üç satırlık deseni izler: framework'ünüz sayfa HTML'ini render eder, renderRoute() config'ten .luis kaynaklarını çözüp SSR artifact'larını enjekte eder, siz de result.html gönderirsiniz.

---

Tek Seferlik Kurulum

Route-kaynak eşlemelerini luis.config.mjs içinde bir kez tanımlayın:

import { defineLuisConfig } from '@lentystyle/core'

export default defineLuisConfig({
  ssr: {
    // Tam uygulama sayfaları kendi script'lerini taşır.
    htmlGuardMode: 'hybrid',
    routes: [
      { match: ['/', '/blog/**'], sources: ['styles/base.luis'] },
      { match: '/docs/**', sourceDirs: ['styles/docs'] },
    ],
  },
})

Ardından entegrasyonu server açılışında bir kez oluşturun:

import { createLentySsrProdFromProjectConfig } from '@lentystyle/ssr'

const ssr = await createLentySsrProdFromProjectConfig()

İpucu

createLentySsrProdFromProjectConfig() render'ları route snapshot'ı başına cache'ler ve .luis dosyaları diskte değiştiğinde otomatik yeniden yükler. Render cache istemiyorsanız createLentySsrFromProjectConfig() kullanın.

---

Express / Node HTTP

import express from 'express'
import { createLentySsrProdFromProjectConfig, isLentySsrError } from '@lentystyle/ssr'

const app = express()
const ssr = await createLentySsrProdFromProjectConfig()

app.get('*', async (req, res, next) => {
  try {
    const html = await renderAppHtml(req) // framework render'ınız
    const render = await ssr.renderRoute(req.path, html)
    res.type('html').send(render.result.html)
  } catch (error) {
    if (isLentySsrError(error)) {
      res.status(500).send(`SSR failed: ${error.code}`)
      return
    }
    next(error)
  }
})

---

Astro Middleware

src/middleware.ts

import { defineMiddleware } from 'astro:middleware'
import { createLentySsrProdFromProjectConfig } from '@lentystyle/ssr'

const ssrReady = createLentySsrProdFromProjectConfig()

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next()
  if (!response.headers.get('content-type')?.includes('text/html')) {
    return response
  }
  const ssr = await ssrReady
  const render = await ssr.renderRoute(context.url.pathname, await response.text())
  return new Response(render.result.html, response)
})

---

Vite Dev Server

// vite.config.ts plugin parçası
import { createLentySsrFromProjectConfig } from '@lentystyle/ssr'

export function lentySsrPlugin() {
  const ssrReady = createLentySsrFromProjectConfig()
  return {
    name: 'lenty-ssr',
    transformIndexHtml: {
      order: 'post',
      async handler(html, context) {
        const ssr = await ssrReady
        const result = await ssr.renderRoute(context.path, html)
        return result.html
      },
    },
  }
}

---

Statik Çıktı mı Var?

Framework'ünüz statik HTML dosyaları üretiyorsa (Astro static, SSG build'leri) request-time entegrasyona hiç ihtiyacınız yok — build çıktısı üzerinde sıfır config CLI'ı çalıştırın:

npx lenty-ssr

Runner detayları için Giriş sayfasına bakın.

---

Response Sonrası: Client-Side DOM Değişiklikleri

SSR'ın işi result.html gönderildiğinde biter — bir sunucu-render html snapshot'ını zenginleştirir, sonrasında browser'da ne olacağını bilmez.

dynamic/observed olarak işaretlenmiş .luis selector'ları için, browser runtime hydration sonrası DOM'u izlemeye devam eder ve bir eşleşme oluşunca CSS'i otomatik enjekte eder (bkz. hybrid Browser Runtime docs).

initial olarak işaretlenmiş selector'lar (yalnızca SSR/build-time snapshot'ına karşı gözlemlenir) için tablo farklı: SSR anında eşleşmeyen bir selector, yalnızca uygulamanız açıkça bir DOM değişikliği sinyali verdiğinde yeniden kontrol edilir — otomatik izlenmez. Bu sinyali tetiklemenin iki yolu var:

• createHybridLifecycleAdapter() / createHybridFrameworkEntryAdapter() ile bootstrap yapıyor ve subscribeDomCommit'i framework'ünüzün kendi commit lifecycle'ına (örn. bir React useEffect, bir Vue onUpdated) bağlıyorsanız, bu her commit sonrası otomatik gerçekleşir.
• Aksi halde, initial-mod bir selector'ün şekillendirdiği DOM'u ekleyen/kaldıran her client-side güncellemeden sonra notifyDomBatch()'i kendiniz çağırmalısınız (örn. veri yüklenince görünen bir rozet).

Dikkat

Bu adımı atlamak gerçek, sessiz bir hata modudur: SSR anında eşleşmeyen bir initial-mod rule, sonradan DOM değişirse ve hiçbir yer notifyDomBatch() çağırmazsa CSS'ini asla almaz. Bu, SSR'ın kendi cache'i veya render'ıyla ilgisizdir — SSR kendisine verilen html için her zaman doğru çıktı üretir.

---

Adapter Contract Hakkında

LentySsrAdapterContract (createLentySsrFrameworkAdapter()) framework başına bir gereklilik değil, opsiyonel bir seam'dir. Yalnızca resolveRouteId -> renderHtml -> resolveSources -> finalizeHtml orkestrasyonunu pakete devretmek istediğinizde kullanın — örneğin prod cache hit'lerinde finalizeHtml'in güncel request context'iyle yeniden çağrılmasını istediğinizde. Bunun dışındaki her şey için önerilen yol yukarıdaki config tabanlı renderRoute() yüzeyidir.