SSR Giriş

@lentystyle/ssr, CSS ve runtime payload'ı route HTML snapshot'ına enjekte eden SSR orchestration katmanıdır. Framework HTML'ini kendi başına render etmez; mevcut bir HTML snapshot ve o route'a ait .luis source listesi tüketir.

Compiler -> Hybrid -> SSR -> HTML Response

En Kısa Kurulum

pnpm add @lentystyle/ssr

npm install @lentystyle/ssr

yarn add @lentystyle/ssr

Sıfır Config Runner

En hızlı giriş: siteni build et, ardından paketle gelen CLI'ı çıktı üzerinde çalıştır.

pnpm add @lentystyle/ssr
npx lenty-ssr

Config dosyası yokken runner convention'larla çalışır:

build edilmiş html'i ./dist içinden okur
her sayfa için inline ve linked .luis source'ları otomatik keşfeder
her sayfayı cache-backed SSR pipeline'ından geçirir
sonucu ./dist-ssr içine yazar

Faydalı flag'ler: --dry-run (yazmadan route listesi), --verify (payload artifact kontrolü; opsiyonel --expect-route /docs/), --in-place, --html-dir, --out, --config.

ssr bloğu olan bir luis.config.mjs varsa runner onu otomatik okur; her alan opsiyoneldir:

import { defineLuisConfig } from '@lentystyle/core'

export default defineLuisConfig({
  ssr: {},
})

SSR Ne Yapar

Route HTML snapshot'ı alır
O route için .luis source listesini compile eder
Üretilen CSS'i HTML içine enjekte eder
Route payload'ını <script type="application/json"> olarak yazar
Framework veya server entegrasyonu için adapter seam'leri sunar
Aynı process içinde tekrar eden render'lar için optional in-memory cache sunar
Request HTML ve source envelope girdilerini @lentystyle/core/guard/ssr ile strict modda validate eder

SSR Ne Yapmaz

Framework HTML'ini sizin yerinize render etmez
Browser runtime'ı başlatmaz
Request-time API'de route source'larını auto-discover etmez (lenty-ssr runner otomatik keşfeder)
Distributed cache veya kalıcı storage sunmaz

Guard Profili

SSR request akışı @lentystyle/core/guard/ssr kullanır.

Bu adapter:

varsayılan olarak strict preset'ini kullanır
html'i config'teki htmlGuardMode ile tarar (varsayılan 'ssr'; runner varsayılanı 'hybrid')
'ssr' modunda LentyStyle SSR payload ve bootstrap allowlist'ini strict tutar
geçersiz request HTML veya source envelope girdilerini hybrid compile başlamadan önce bloklar

Default guard akışı

High-level SSR helper'larında guard'ı ayrıca etkinleştirmezsiniz; request render akışının içinde çalışır.

import { renderLentySsrSnapshot } from '@lentystyle/ssr'

await renderLentySsrSnapshot({}, {
  routeId: '/docs/',
  html: '<html><head></head><body><div class="card"></div></body></html>',
  sources: [
    {
      sourceId: 'docs.luis',
      source: '.card { color: #0f172a; }',
    },
  ],
})

Yerleşik davranış sabittir:

preset: 'strict'
htmlMode: 'ssr'

Ne zaman özel guard davranışı gerekir

Public renderLentySsrSnapshot() ve createLentySsrIntegration() yüzeyleri doğrudan guardPolicy kabul etmez. Özel doğrulama gerekiyorsa guard'ı SSR'in bir katman üstünde ayrı çalıştırmalı ya da daha low-level orchestration'a inmelisiniz.

import { scanSnapshotEnvelope } from '@lentystyle/core/guard/ssr'

const findings = scanSnapshotEnvelope(
  {
    routeId: '/docs/',
    html: '<html><head></head><body><div class="card"></div></body></html>',
    sources: [
      {
        sourceId: 'docs.luis',
        source: '.card { color: #0f172a; }',
      },
    ],
  },
  { preset: 'strict', htmlMode: 'ssr' },
)

console.log(findings.length) // 0

Önerilen Başlangıç

Route HTML snapshot'ı üretin
.luis source listesini hazırlayın
Doğru SSR yüzeyini seçin
result.html çıktısını response'a yazın

Mevcut yüzeyler:

renderLentySsrSnapshot() -> tek seferlik render
createLentySsrIntegration() -> yeniden kullanılabilir doğrudan yüzey
createLentySsrFromProjectConfig() -> route-kaynak eşlemeli config tabanlı renderRoute()
createLentySsrProdFromProjectConfig() -> aynı yüzeyin process-local render cache'li hâli
createLentySsrFrameworkAdapter() -> opsiyonel adapter seam'i
createLentySsrProd() -> process-local cache destekli helper
runLentySsrProjectRender() -> lenty-ssr CLI render adımının programatik karşılığı
verifyLentySsrProjectOutput() -> CLI'ın --verify adımının programatik karşılığı

Hızlı Örnek

import { renderLentySsrSnapshot } from '@lentystyle/ssr'

const result = await renderLentySsrSnapshot(
  { mode: 'ssr' },
  {
    routeId: '/docs/',
    html: '<html><head></head><body><div class="card"></div></body></html>',
    sources: [
      {
        sourceId: 'site.luis',
        source: '.card { color: red; }',
      },
    ],
  },
)

Çağrıdan sonra:

result.css üretilen CSS'i içerir
result.runtimePayload hybrid route payload'ını içerir
result.html nihai enjekte edilmiş HTML'i içerir

`luis.config.mjs` Ne Zaman Önemli

Low-level SSR API'leri object tabanlıdır ve luis.config.mjs gerektirmez. Ama app-level preview ve project helper akışlarında ortak SSR ayarlarını aynı config dosyasında tutmak daha faydalıdır.

import { defineLuisConfig } from '@lentystyle/core'

export default defineLuisConfig({
  ssr: {
    mode: 'ssr',
    outDirName: 'dist-ssr',
    defaultRuntimeOptions: '',
    include: ['**/*.html'],
  },
})

SSR İçinde Runtime ve Guard Ayrımı

SSR de convenience ve hardening rollerini ayrı tutar:

browser runtime client tarafında optional ve convenience odaklı kalır
@lentystyle/core/guard/ssr, server tarafında gelen HTML snapshot ve source envelope girdisini sertleştirir

Bu ayrım sayesinde SSR, payload ve bootstrap HTML konusunda strict kalabilirken browser runtime kendi standalone policy modelini korur.

Hatalar

Her SSR hatası kodlu bir LentySsrError ile reject olur:

import { isLentySsrError } from '@lentystyle/ssr'

try {
  await integration.renderRequest(input)
} catch (error) {
  if (isLentySsrError(error)) {
    console.log(error.code) // 'guard-rejected' | 'compile-failed' | 'adapter-callback-failed' | 'project-config-invalid'
  }
}

Kod	Anlamı
`guard-rejected`	request html'i veya source envelope'u guard doğrulamasını geçemedi
`compile-failed`	alttaki hybrid compile adımı başarısız oldu
`adapter-callback-failed`	bir adapter contract callback'i (`resolveRouteId`, `renderHtml`, `resolveSources`, `finalizeHtml`) hata fırlattı
`project-config-invalid`	`luis.config.mjs` içindeki `ssr` bloğu veya bir `routes` eşlemesi geçersiz; hata belirli bir route'a bağlıysa `error.routeId` doludur

Sonraki Adım

Request-level ve project-level ayarlar için Config
Express, Astro ve Vite request-time tarifleri için Framework'ler
Browser tarafı convenience davranışı için Browser Runtime
Fail-closed validation modeli için @lentystyle/guard dokümanları