SSR Ayarlar

Bu sayfa @lentystyle/ssr içindeki iki ayrı config katmanını açıklar:

request-time render için LentySsrConfig
luis.config.mjs içindeki project-level ssr bloğu

En Kısa Kurulum

pnpm add @lentystyle/ssr

npm install @lentystyle/ssr

yarn add @lentystyle/ssr

İki Ayrı Config Katmanı

Request Config
Project Config

LentySsrConfig, renderLentySsrSnapshot(), createLentySsrIntegration() ve diğer request-time SSR yüzeylerine geçen public config tipidir.

Bu katman:

runtime option default'larını tanımlar
HTML injection metadata'sını taşır
mode, adapter ve rewritePolicy gibi alanları resolved biçimde tutar

LuisSsrProjectConfig, luis.config.mjs içindeki ssr bloğudur.

Bu katman:

paylaşılan app-level preview ayarlarını tutar
outDirName, include, exclude ve maxEntries gibi alanlar ekler
loadLuisSsrProjectConfig() üzerinden yüklenir

`LentySsrConfig`

interface LentySsrConfig {
  mode?: 'static' | 'ssr'
  adapter?: 'none' | 'vue' | 'svelte' | 'react' | 'astro'
  performance?: boolean
  debug?: boolean
  map?: boolean
  lazy?: boolean
  worker?: 'auto' | 'main' | 'worker'
  assetBaseUrl?: string
  globalCssHref?: string
  bootstrapScriptSrc?: string
  runtimeOptions?: string | Partial<LentySsrRuntimeOptions>
  rewritePolicy?: 'auto' | 'prefer-static' | 'prefer-runtime'
}

Varsayılanlar

Field	Default
`mode`	`'ssr'`
`adapter`	`'none'`
`debug`	`false`
`performance`	`false`
`map`	`false`
`lazy`	`false`
`worker`	`'auto'`
`assetBaseUrl`	`/_hybrid`
`globalCssHref`	`null`
`bootstrapScriptSrc`	`null`
`rewritePolicy`	`'auto'`
`output.payloadMode`	`'inline-json'`

Hızlı Örnek

import { createLentySsrIntegration } from '@lentystyle/ssr'

const ssr = createLentySsrIntegration({
  mode: 'ssr',
  globalCssHref: '/assets/site.css',
  bootstrapScriptSrc: '/assets/browser-entry.js',
  runtimeOptions: 'performance,!worker',
})

Bu örnekte:

ortak global CSS her render'da <link rel="stylesheet"> olarak enjekte edilir
bootstrap script her render'da enjekte edilir
runtime options çözümlemesi performance: true ve worker: 'main' verir

Yerleşik Guard Ayarları

SSR request helper'ları kendi dahili guard policy'si ile gelir; config üzerinden guardPolicy geçmezsiniz.

Surface	Guard behavior
`renderLentySsrSnapshot()`	`preset: 'strict'`, `htmlMode: 'ssr'`
`createLentySsrIntegration().renderRequest()`	`preset: 'strict'`, `htmlMode: 'ssr'`
`createLentySsrFrameworkAdapter().render()`	`preset: 'strict'`, `htmlMode: 'ssr'`

Kısa örnek:

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; }',
    },
  ],
})

Ek guard config vermeseniz bile bu çağrı request envelope'u validate eder ve downstream hybrid compile adımında strict doğrulamayı korur.

Runtime Option Merge Sırası

SSR içindeki runtime option merge sırası sabittir:

package defaults
-> config.debug / performance / map / lazy / worker
-> config.runtimeOptions
-> source.runtimeOptions

Temel default'lar uygulanır

{
  debug: false,
  performance: false,
  map: false,
  lazy: false,
  worker: 'auto',
}

Top-level config flag'leri uygulanır
debug, performance, map, lazy ve worker bu aşamada uygulanır.
config.runtimeOptions patch'i uygulanır
String veya object patch, top-level flag'leri override eder.
Source-level override uygulanır
input.sources[].runtimeOptions, config-level sonucu source bazında override eder.

String syntax

runtimeOptions: 'debug,performance,!worker'

Sonuç:

{
  debug: true,
  performance: true,
  map: false,
  lazy: false,
  worker: 'main',
}

Desteklenen token'lar:

debug, performance, map, lazy
!debug, !performance, !map, !lazy
worker -> worker: 'worker'
!worker -> worker: 'main'

Source-level override örneği

const result = await renderLentySsrSnapshot(
  { runtimeOptions: 'debug,worker' },
  {
    routeId: '/docs/',
    html,
    sources: [
      {
        sourceId: 'docs.luis',
        source,
        runtimeOptions: '!debug,lazy,!worker',
      },
    ],
  },
)

Bu source için final runtime options:

{
  debug: false,
  performance: false,
  map: false,
  lazy: true,
  worker: 'main',
}

Request-level default ve source-level override birlikte

Config:

const config = {
  runtimeOptions: 'debug,performance,worker',
}

Source:

const input = {
  routeId: '/docs/',
  html: '<html><head></head><body><div class="card"></div></body></html>',
  sources: [
    {
      sourceId: 'docs.luis',
      source: '.card { color: #0f172a; }',
      runtimeOptions: '!debug,lazy,!worker',
    },
  ],
}

Bu source için final runtime options:

{
  debug: false,
  performance: true,
  map: false,
  lazy: true,
  worker: 'main',
}

`luis.config.mjs` İçindeki `ssr` Bloğu

Project-level SSR config tipi LuisSsrProjectConfig'dir. LentySsrConfig alanlarını devralır ve preview veya project-level alanlar ekler.

import { defineLuisConfig } from '@lentystyle/core'

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

Ek project alanları

Field	Purpose	Default
`outDirName`	Preview HTML kök dizininin adı	`'dist-ssr'`
`maxEntries`	Prod helper için app-level cache limiti	`100`
`defaultRuntimeOptions`	Project-level source'lara merge edilen varsayılan runtime option string'i	`''`
`include`	Dahil edilecek relative HTML path pattern'leri	`[]`
`exclude`	Atlanacak relative HTML path pattern'leri	`[]`

Project-level default örneği

import { defineLuisConfig } from '@lentystyle/core'

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

Bu kurulumda defaultRuntimeOptions, auto-discovered source'lara ortak bir baseline verir. Bir source farklı davranmalıysa source-level runtimeOptions ile override edin.

Project Config Nasıl Yüklenir

`loadLuisSsrProjectConfig(configOrPath?, overrides?)`

import { loadLuisSsrProjectConfig } from '@lentystyle/ssr'

const config = await loadLuisSsrProjectConfig(undefined, { cwd: appDir })

Bu helper:

luis.config.mjs dosyasını yükler
ssr bloğunu okur
request-level config alanlarını çözümler
outDirName, maxEntries, include ve exclude gibi project-level default'ları uygular

Validation kuralları:

config dosyası gerçek bir ssr object export etmiyorsa throw eder
include ve exclude verildiyse string array olmalıdır
outDirName boş olamaz ve / ile \ içeremez

Normalize edilmiş sonuç

{
  configPath: '.../luis.config.mjs',
  configDir: '.../apps/site',
  outDirName: 'dist-ssr',
  outDir: '.../apps/site/dist-ssr',
  maxEntries: 100,
  defaultRuntimeOptions: '',
  include: [],
  exclude: [],
  runtimeOptions: {
    debug: false,
    performance: false,
    map: false,
    lazy: false,
    worker: 'auto',
  },
}

`include` ve `exclude` Nasıl Çalışır

shouldProcessLuisSsrProjectHtmlFile(htmlFilePath, config) üretilen HTML yolunu config.outDir altındaki relative path'e çevirir ve pattern match yapar.

import {
  loadLuisSsrProjectConfig,
  shouldProcessLuisSsrProjectHtmlFile,
} from '@lentystyle/ssr'

const config = await loadLuisSsrProjectConfig(undefined, { cwd: appDir })

shouldProcessLuisSsrProjectHtmlFile(
  `${appDir}/dist-ssr/docs/index.html`,
  config,
)

Match kuralları:

include boşsa dosya varsayılan olarak dahil edilir
include boş değilse en az bir pattern eşleşmelidir
sonra exclude eşleşirse dosya reddedilir

ssr: {
  include: ['docs/**', 'blog/**'],
  exclude: ['blog/drafts/**'],
}

Relative path	Decision
`docs/index.html`	işlenir
`blog/post-1/index.html`	işlenir
`blog/drafts/demo/index.html`	atlanır
`admin/index.html`	atlanır

Desteklenen küçük-glob davranışı:

*
**
?

Path normalization her zaman / kullanır.

Bilinmesi Gereken Sınırlar

assetBaseUrl, mode, adapter ve rewritePolicy resolved config içinde taşınır; mevcut request-time SSR akışı bunların her biri için HTML davranışını ayrı ayrı dallandırmaz
output.payloadMode şu anda yalnızca 'inline-json'
defaultRuntimeOptions project-level metadata'dır; low-level render API bunu doğrudan okumaz
include ve exclude yalnızca generated HTML relative path'lerine göre karar verir; source discovery yapmaz