İstemci tarafında işleme

EffCSS, siz hiçbir ekstra çaba harcamadan halihazırda istemci tarafında çalışmaktadır. Bununla birlikte, sunucu tarafı işlemede (SSR) yaygın olarak kullanılan stil "hydration" (hidrasyon) mekanizması, vite-plugin-effcss kullanılarak istemci tarafı işleme (CSR) için de kullanılabilir.

Bu eklenti, Vite SSR işlem hattı aracılığıyla EffCSS tarafından üretilen CSS'i yakalar ve doğrudan HTML içine gömer (inline eder). Böylece FOUC (Stilsiz İçeriğin Görünmesi) sorunu ortadan kaldırılır ve stil hidrasyonu sayesinde ilk oluşturma (rendering) süreci hızlandırılır. Hem geliştirme hem de derleme modlarında, hiçbir ek bağımlılık gerektirmeden (esbuild, tsx veya fazladan yükleyiciler olmadan) çalışır.

Sıfır yapılandırma — herhangi bir ayar gerektirmeden çalışır. Sadece eklenti dizinize (plugins array) eklemeniz yeterlidir.

CSR odaklı — SSR/SSG için manuel serialize() ve serializeMeta() kullanın. Ayrıntılar için Sunucu tarafı oluşturma bölümüne bakın.

Eklenti kullanımı

Öncelikle, eklentiyi projenize yüklemeniz gerekir:

npm install vite-plugin-effcss --save-dev

EffCSS bir eş bağımlılık (peer dependency) olarak tanımlanmıştır; projenizde yüklü olduğundan emin olun:

npm install effcss

Ardından bunu Vite yapılandırmasına ekleyin:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import effcss from 'vite-plugin-effcss';

export default defineConfig({
  plugins: [react(), effcss()],
});

HTML'nize bir yer tutucu ekleyin (isteğe bağlıdır; belirtilmezse </head> etiketi öncesine yerleştirilir):

<head>
  <!-- EFFCSS_INJECT -->
</head>

İşte bu kadar. Eklenti, EffCSS tarafından üretilen tüm CSS'i yakalar ve bunu HTML'inize satır içi (inline) olarak ekler.

Eklentinin prefix, minify ve diğer EffCSS ayarlarını yönetmediğini unutmayın; bu ayarlar kendi kaynak kodunuzda configure() aracılığıyla yapılandırılmalıdır:

// src/effcss-config.ts
import { configure } from 'effcss';

configure({
  prefix: 'my',
  minify: true,
});

Seçenekler

Eklenti şu seçenekleri destekler:

Seçenek	Tür	Varsayılan	Açıklama
verbose	boolean	false	Ayrıntılı eklenti günlükleri
entry	string	—	Açıkça belirtilen giriş noktası (ör. /src/main.tsx). Belirtilmediği takdirde index.html içindeki <script type="module" src="..."> ifadesinden otomatik olarak algılanır
placeholder	string	'<!-- EFFCSS_INJECT -->'	<style> ile değiştirilecek HTML yer tutucusu
injectTo	'head' | 'head-prepend' | 'body'	'head'	Yer tutucu bulunamazsa yedek enjeksiyon pozisyonu
injectMeta	boolean	true	serializeMeta() fonksiyonunu JSON meta verileriyle birlikte bir <script> etiketi olarak enjekte edin

Nasıl çalışır

                    buildStart()
                          │
                 ┌─────────┴─────────┐
                 │                   │
                 ▼                   ▼
           Server exists?      Server null?
           (dev mode)          (build mode)
                 │                   │
                 ▼                   ▼
      write tmp .ts file     createServer() + virtual module
      → ssrLoadModule        → ssrLoadModule('effcss:capture')
                 │                   │
                 └───────┬───────────┘
                         ▼
               mod.css + mod.meta
                         │
                         ▼
               transformIndexHtml
               → inject <style> + <script>

Eklenti, şunları yapan bir yakalama modülü (capture module) oluşturur:

1. EffCSS'i içe aktarır (serialize() / serializeMeta() fonksiyonlarına erişmek için)
2. Giriş noktanızı (entry point) içe aktarır — stilleri çalıştırmak ve kaydetmek için
3. serialize() fonksiyonunu çağırır — nihai CSS ve meta verilerini dizge (string) olarak yakalar
4. Sonuçları HTML'inize gömer (inline eder) — transformIndexHtml aracılığıyla

Geliştirme modu (Dev mode) — geçici bir .ts dosyası ile mevcut ViteDevServer'ı kullanır ve ardından bu dosyayı temizler.

Derleme modu (Build mode) — createServer() aracılığıyla geçici bir Vite geliştirme sunucusu oluşturur; resolveId/load kancalarıyla (hooks) sanal bir 'effcss:capture' modülü kaydeder; bu modülü ssrLoadModule() ile yükler ve sunucuyu kapatır. JSX, SVG ve CSS içe aktarımlarının düzgün bir şekilde dönüştürülmesi için kullanıcı eklentileri (React, Vue vb.) sürece dahil edilir. Eklenti, sonsuz özyinelemeyi (infinite recursion) önlemek amacıyla kendisini bu iç içe sunucu sürecinin dışında tutar.

Teknik notlar

• Vite: ^5.0.0 || ^6.0.0
• EffCSS: ^5.4.0
• Çalışma Zamanı: EffCSS tarayıcı paketinde kalır