Hybrid Ayarlar

Bu sayfa @lentystyle/hybrid için genelde ihtiyaç duyduğunuz ayarları toplar. Amaç, low-level API'lere inmeden şu sorulara yanıt vermektir:

• hangi dosyayı oluştururum
• hangi alanları ayarlarım
• build ve dev nasıl davranır
• varsayılanlar nelerdir
• ne zaman config-driven kalırım, ne zaman low-level guard kontrolüne inerim

Not

Önerilen akışta yalnızca luis.config.mjs yazarsınız ve build ile dev aynı config'i yeniden kullanır. Low-level API'ler hâlâ vardır, fakat ilk kurulum için gerekli değildir.

---

En Kısa Kurulum

Kurulum komutu için paket yöneticinizi seçin:

pnpm

pnpm add @lentystyle/hybrid

npm

npm install @lentystyle/hybrid

yarn

yarn add @lentystyle/hybrid

1. @lentystyle/hybrid kurun

2. Proje kökünde luis.config.mjs oluşturun

3. hybrid bloğunu tanımlayın

4. Build script'ini çalıştırın

---

Minimal luis.config.mjs Örneği

import { defineLuisConfig } from '@lentystyle/core/config'

export default defineLuisConfig({
  hybrid: {
    buildMode: 'initial',
    sourceRoots: ['./public', './dist'],
    luisOutputDir: './dist/_hybrid',
    assetBaseUrl: '/_hybrid',
    globalCssFileName: 'lentystyle-global.css',
    defaultRuntimeOptions: '',
  },
})

Build script'i:

{
  "scripts": {
    "build": "astro build && pnpm exec lentystyle-hybrid build"
  }
}

Generic dev middleware örneği:

import { defineMiddleware } from 'astro:middleware'
import { createHybridProjectDevMiddleware } from '@lentystyle/hybrid'

const hybridDev = await createHybridProjectDevMiddleware()

export const onRequest = defineMiddleware((context, next) =>
  hybridDev(context.request, () => next()),
)

---

Varsayılanlar

Bir alan atlanırsa temel default'lar şunlardır:

Field	Default
buildMode	'initial'
htmlOutputDir	'./dist'
assetBaseUrl	''
globalCssFileName	'lentystyle-global.css'
globalManifestFileName	'lentystyle-global.manifest.json'
writeRouteCssArtifacts	false
defaultRuntimeOptions	undefined
hybridOptions	undefined
rewrite	'auto'
include	[]
exclude	[]

Pratikte:

• buildMode yoksa varsayılan 'initial' modu çalışır: route HTML taranır, tek CSS + tek manifest üretilir ve source taşıyan HTML dosyalarına generated global CSS link'i yazılır
• htmlOutputDir yoksa hybrid route HTML dosyalarını ./dist altından okur
• assetBaseUrl yoksa rewrite edilen asset URL'leri ek prefix almaz
• globalCssFileName yoksa ortak generated CSS lentystyle-global.css adıyla yazılır
• globalManifestFileName yoksa global manifest lentystyle-global.manifest.json adıyla yazılır
• writeRouteCssArtifacts yoksa route modu route başına .css dosyası yazmaz
• defaultRuntimeOptions yoksa source-level data-luis değerleri kendi başına geçerli olur

---

En Önemli Ayarlar

Field	Ne yapar	Ne zaman gerekir
buildMode	'initial' (varsayılan): route HTML taramasıyla tek CSS + manifest ve generated CSS link injection. 'global': source-only compile, tek CSS + manifest, ayrıca htmlOutputDir explicit ise generated CSS link injection. 'route': route payload'ları	Her zaman; route HTML çıktısı yoksa açıkça 'global' kullanın
htmlOutputDir	Route HTML dosyalarını içeren framework build çıktı klasörü	Çıktı klasörünüz ./dist dışında ise değiştirin
sourceRoots	.luis source keşfinin yapılacağı kökler	Her zaman
luisOutputDir	Generated LentyStyle CSS, manifest ve payload artifact çıktılarının dizini	Her zaman
assetBaseUrl	Rewrite edilen HTML içindeki asset prefix'i	Düz URL yerine özel prefix istiyorsanız
globalCssFileName	Ortak generated CSS dosya adı	Default lentystyle-global.css adı asset isimlendirme düzeninizle çakışıyorsa
globalManifestFileName	Global manifest JSON dosya adı	Default lentystyle-global.manifest.json adı çakışıyorsa
writeRouteCssArtifacts	Route modunda işlenen her route için ayrıca route-scope .css dosyası yazar	Route CSS asset'lerini doğrudan fetch eden consumer'lar için
defaultRuntimeOptions	Discovered .luis source'larına merge edilen, kullanıcıya giden runtime davranışı	Generated manifest debug, performance, map, lazy veya worker istesin diyorsanız
hybridOptions	Terminalde görülen hybrid compile ve rewrite diagnostic logları	Kullanıcıya giden runtime çıktısını değiştirmeden hybrid debug veya performance logları istiyorsanız
rewrite	Source .luis tag'leri için rewrite policy	Runtime-vs-static çıktıyı kontrol etmek istiyorsanız
include / exclude	Hangi HTML veya .luis candidate'larının işleneceği	Projenin sadece belirli kısmını işlemek istiyorsanız

---

Ayarlar Ne Zaman Uygulanır

Build

Build modunda runHybridProjectBuild() veya CLI önce config'i yükler:

• buildMode: 'initial' (varsayılan): route HTML dosyaları taranır, non-observed + ilk snapshot'ta eşleşen ?/?! observed kurallar tek global CSS'e yazılır, eşleşmeyen observed kurallar runtime manifest'inde kalır ve source taşıyan HTML dosyalarına generated global CSS link'i ile observed-only source marker'ları yazılır
• buildMode: 'global': tüm .luis source'ları boş HTML'e karşı derlenir, luisOutputDir altına tek globalCssFileName + tek globalManifestFileName yazılır; tüm observed kurallar runtime manifest'inde kalır. htmlOutputDir explicit verilmişse ve mevcutsa generated global CSS link'i ile observed-only source marker'ları route HTML dosyalarına da yazılır
• buildMode: 'route': route-aware HTML modu htmlOutputDir altındaki route HTML dosyalarını okur ve route payload artifact'lerini luisOutputDir altına yazar
• include ve exclude hangi candidate'ların taranacağını filtreler
• route-scope CSS dosyaları writeRouteCssArtifacts: true olmadıkça atlanır (yalnızca route modu)

Dev

Dev modunda createHybridProjectDevIntegration() veya createHybridProjectDevMiddleware() aynı config'i yeniden kullanır:

• in-memory asset üretir
• buildMode: 'global' configured .luis köklerinden startup'ta derlenmiş tek CSS + manifest servis eder
• buildMode: 'initial' her dev route response'unu geldikçe tek paylaşılan in-memory CSS + manifest'e derler; route değişiminde tüm route'ları yeniden taramaz
• buildMode: 'route' HTML response'larını route bazında rewrite eder
• sourceRoots, defaultRuntimeOptions, hybridOptions, rewrite, include ve exclude alanları build'dekiyle aynı şekilde etki eder
• in-memory ortak generated CSS'i assetBaseUrl/globalCssFileName yolundan servis eder

---

Yerleşik Guard Varsayılanları ve Override Noktası

Hybrid guard davranışı aktif akışa göre değişir.

Flow	Built-in guard behavior
Global mode	preset: 'trusted-build', allowedLocalRoots: sourceRoots
Initial mode ve route-aware HTML mode	preset: 'balanced', htmlMode: 'hybrid'
Manual compileHybridBundle({...})	Varsa sizin verdiğiniz guardPolicy

Varsayılan config-driven akış:

import { runHybridProjectBuild } from '@lentystyle/hybrid'

await runHybridProjectBuild()

Bu çağrı hybrid bloğunu okur ve buildMode değerine göre global, initial veya route davranışını seçer.

Özel policy örneği:

import { compileHybridBundle } from '@lentystyle/hybrid/node'

await compileHybridBundle({
  routeId: '/docs/',
  html: '<html><head></head><body><div class="card"></div></body></html>',
  guardPolicy: {
    preset: 'strict',
    htmlMode: 'hybrid',
    allowedLocalRoots: ['D:/project/public/styles'],
    allowedRemoteImportOrigins: ['https://cdn.example.com'],
  },
  sources: [
    {
      sourceId: '/styles/docs.luis',
      source: '.card { color: #0f172a; }',
    },
  ],
})

Not

luis.config.mjs içindeki hybrid bloğu şu anda guardPolicy kabul etmez. Özel guard davranışı gerektiğinde low-level Node API'sini kullanın.

---

rewrite İçin Pratik Kural

rewrite şu değerleri kabul eder:

• 'auto'
• 'always'
• 'never'

Günlük kullanımda önerilen default:

rewrite: 'auto'

Pratikte:

• route runtime gerektirmiyorsa source .luis tag'leri kaldırılabilir
• üretilen CSS link'leri yerinde kalır
• runtime gereken route'lar source tag'lerini koruyabilir

Dikkat

debug, performance, map, lazy, worker veya observed rule'lar gibi runtime feature'lar bir route'u tamamen static olmak yerine runtime-driven durumda bırakabilir.

---

sourceRoots Sırası Önemlidir

sourceRoots sırası önemlidir.

Örnek:

sourceRoots: ['./public', './dist']

Bu sıra genelde daha güvenlidir; çünkü eski dist çıktısının canlı public source'ların önüne geçmesini engeller.

Yanlış sıranın tipik sonuçları:

• son source değişikliğiniz görünmez
• dev sırasında eski .luis içeriği çözülür
• beklenen selector'lar generated CSS içinde çıkmaz

---

Runtime Options ve Hybrid Diagnostics Farkı

Bu iki alan aynı token parser'ını kullanır, fakat farklı yerlere etki eder.

defaultRuntimeOptions: 'performance', // kullanıcıya giden runtime davranışı
hybridOptions: 'debug,performance',   // terminalde görülen hybrid diagnostics

defaultRuntimeOptions auto-discovered her .luis source'una merge edilir. Sonuç generated manifest veya payload içine girer ve browser runtime'ın ne yapabileceğini değiştirir.

hybridOptions hybrid build/dev süreci tarafından okunur. Compile timing, warning ve rewrite-decision loglarını kontrol eder. Generated runtime options değerlerini değiştirmez.

Desteklenen defaultRuntimeOptions token'ları:

• debug / !debug
• performance / !performance
• map / !map
• lazy / !lazy
• worker / !worker

hybridOptions aynı şekli kabul eder, fakat şu anda hybrid diagnostics için anlamlı olanlar şunlardır:

• performance: hybrid compile/evaluate timing loglarını yazar
• debug: hybrid compile warning ve rewrite-decision loglarını yazar

Object formu da desteklenir:

defaultRuntimeOptions: {
  performance: true,
  lazy: true,
  worker: 'auto',
}

Genel öneri:

• kullanıcıya giden runtime default'u: defaultRuntimeOptions: 'performance'
• build/dev diagnostic logları: hybridOptions: 'debug,performance'
• default istemiyorsanız: alanı atlayın veya '' kullanın

Not

Boş değer geçerlidir. Runtime option kullanmak zorunlu değildir.

Source-level override örneği

defaultRuntimeOptions, auto-discovered source'lara uygulanır. Source-level data-luis yine source başına bu default'u override eder.

Config:

hybrid: {
  buildMode: 'initial',
  htmlOutputDir: './dist',
  sourceRoots: ['./public'],
  luisOutputDir: './dist/_hybrid',
  defaultRuntimeOptions: 'debug,performance',
}

HTML:

<link rel="stylesheet" href="/styles/docs.luis" data-luis="!debug,lazy">

Bu source için efektif runtime options:

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