Modern web uygulamaları geliştirirken, kullanıcı deneyimini ve arama motoru optimizasyonunu (SEO) iyileştirmek amacıyla Sunucu Tarafı Render (SSR) teknikleri giderek daha popüler hale gelmektedir. Vue.js ekosisteminde Nuxt.js gibi çerçeveler, SSR’ı kolaylaştırırken, bazı durumlarda bu süreç beklenmedik sorunlara yol açabilir. Özellikle tarayıcıya özgü API’lere (window, document, localStorage vb.) bağımlı olan Vue bileşenleri, sunucu ortamında render edilmeye çalışıldığında hatalara neden olabilir. İşte tam bu noktada vue-no-ssr kütüphanesi devreye girerek bu tür bileşenleri akıllıca gizlememize ve uygulamanın geri kalanının sorunsuz bir şekilde SSR ile çalışmasını sağlamamıza olanak tanır.
Bu rehberde, vue-no-ssr‘ın ne olduğunu, neden ihtiyaç duyduğumuzu, nasıl kurulup kullanılacağını ve pratik uygulamalarda dikkat edilmesi gerekenleri detaylı bir şekilde inceleyeceğiz. Amacımız, SSR tabanlı Vue projelerinizde karşılaştığınız bu yaygın sorunu çözmek için size kapsamlı bir yol haritası sunmaktır.
SSR ve Zorlukları: Neden Bazı Bileşenler Sorun Yaratır?
Sunucu Tarafı Render (SSR), bir Vue uygulamasının HTML çıktısının sunucuda oluşturulup tarayıcıya gönderilmesini ifade eder. Bu, ilk yükleme hızını artırır ve arama motorlarının içeriği daha kolay indekslemesini sağlar. Ancak, sunucu ortamı bir tarayıcı ortamından farklıdır. Sunucuda bir DOM (Belge Nesne Modeli), window nesnesi, document nesnesi veya localStorage gibi tarayıcıya özgü API’ler bulunmaz.
Birçok Vue bileşeni, özellikle üçüncü taraf kütüphanelerle entegre olanlar veya doğrudan tarayıcı API’lerini kullananlar, bu eksiklik nedeniyle sunucuda render edilmeye çalışıldığında hatalara neden olur. Örneğin:
window.innerWidth veya document.querySelector gibi DOM manipülasyonları yapan bileşenler.localStorage.getItem() veya sessionStorage.setItem() gibi tarayıcı depolama API’lerini kullanan bileşenler.Chart.js, Mapbox GL JS, Fabric.js gibi Canvas veya WebGL tabanlı grafik kütüphaneleri.- Tarayıcıya özgü olay dinleyicileri (örn.
resize, scroll) ekleyen bileşenler.
Bu tür bileşenler, sunucuda çalıştığında “window is not defined” veya “document is not defined” gibi hatalar fırlatarak uygulamanın SSR sürecini durdurur. Bu da uygulamanın tamamen SSR yeteneğini kaybetmesine veya hatalı çalışmasına yol açar. İşte bu noktada vue-no-ssr gibi çözümler, bu bileşenleri yalnızca istemci tarafında render ederek sorunu ortadan kaldırır.
vue-no-ssr Nedir ve Nasıl Çalışır?
vue-no-ssr, tarayıcıya özgü API’lere bağımlı olan Vue bileşenlerini sunucu tarafında render edilmekten koruyan basit ama etkili bir wrapper (sarmalayıcı) bileşendir. Temel prensibi şudur:
- Sunucu Tarafında: bileşeni, içerdiği bileşeni render etmez. Bunun yerine, varsayılan olarak boş bir HTML yorumu veya isteğe bağlı olarak belirleyeceğiniz bir placeholder (yer tutucu) render eder. Bu sayede sunucuda hiçbir tarayıcı API’si çağrılmaz ve hata oluşmaz.
- İstemci Tarafında (Tarayıcıda): Uygulama tarayıcıya yüklendikten ve Vue hidrasyon süreci tamamlandıktan sonra, bileşeni, içerdiği gerçek bileşeni render eder. Bu noktada, tüm tarayıcı API’leri kullanılabilir durumdadır ve bileşen sorunsuz bir şekilde çalışır.
Bu yaklaşım, uygulamanızın genel olarak SSR yeteneğini korurken, yalnızca belirli “sorunlu” bileşenlerin istemci tarafında yüklenmesini garanti eder. Böylece hem hızlı ilk yükleme ve SEO avantajlarından yararlanabilir hem de tarayıcıya özgü işlevsellikleri kullanabilirsiniz.
vue-no-ssr Kurulumu ve Kullanımı
vue-no-ssr‘ı projenize entegre etmek oldukça basittir.
Kurulum
Öncelikle, kütüphaneyi projenize npm veya yarn ile eklemeniz gerekir:
npm install vue-no-ssr
veya
yarn add vue-no-ssr
Temel Kullanım
Kullanımı, sorunlu bileşeninizi etiketi içine sarmalamaktan ibarettir.
Örnek olarak, tarayıcı genişliğini gösteren basit bir bileşen düşünelim. Bu bileşen window nesnesine eriştiği için sunucuda hata verecektir:
Şimdi bu bileşeni uygulamanızda kullanırken vue-no-ssr ile sarmalayalım:
Bu sayede WindowWidthDisplay bileşeni sunucuda render edilmeyecek, sadece tarayıcıda yüklendikten sonra görünecektir.
Özelleştirme
vue-no-ssr bileşeni, sunucu tarafında gösterilecek yer tutucuyu özelleştirmeniz için bazı prop’lar sunar:
ssr-placeholder Prop’u
Sunucu tarafında render edilecek bir string veya HTML parçası belirleyebilirsiniz. Bu, kullanıcıya bileşenin yüklendiğini veya henüz mevcut olmadığını bildirmek için faydalıdır.
Bu örnekte, sunucuda “Genişlik bilgisi yükleniyor…” yazısı veya bir iskelet yükleyici (skeleton loader) görünecek, istemcide ise gerçek bileşenler yüklenecektir.
ssr-tag Prop’u
Eğer ssr-placeholder kullanmıyorsanız ve varsayılan HTML yorumu yerine belirli bir HTML etiketi render edilmesini istiyorsanız ssr-tag prop’unu kullanabilirsiniz. Örneğin, sunucuda bir div etiketi render etmek için:
Varsayılan olarak vue-no-ssr, sunucuda
Harita Yükleniyor...
Lütfen bekleyiniz.
Global Kayıt (İsteğe Bağlı)
Eğer bileşenini uygulamanızın birçok yerinde kullanacaksanız, her dosyada import etmek yerine global olarak kaydedebilirsiniz. Bu, Vue uygulamanızın ana dosyasında (genellikle main.js veya app.js) yapılır:
// main.js
import { createApp } from 'vue';
import App from './App.vue';
import NoSsr from 'vue-no-ssr';
const app = createApp(App);
// NoSsr bileşenini 'no-ssr' adıyla global olarak kaydet
app.component('no-ssr', NoSsr);
app.mount('#app');
Artık uygulamanızın herhangi bir yerinde etiketini doğrudan kullanabilirsiniz, import etmenize gerek kalmaz.
Pratik İpuçları ve Dikkat Edilmesi Gerekenler
vue-no-ssr güçlü bir araç olsa da, kullanımında bazı önemli noktaları göz önünde bulundurmak gerekir.
Ne Zaman Kullanmalı?
- Gerçekten tarayıcıya özgü API’lere (
window, document, localStorage, navigator vb.) bağımlı olan bileşenler için.
- Üçüncü taraf kütüphaneler (örneğin, harita kütüphaneleri, grafik kütüphaneleri, bazı UI bileşenleri) sunucuda hata veriyorsa.
- Sadece istemcide çalışması gereken etkileşimli bileşenler için.
Performans ve SEO Etkisi
-
SEO: içinde sarmalanan içerik, ilk HTML render’ında sunucudan gelmediği için arama motoru botları tarafından doğrudan indekslenmeyebilir. Eğer bu bileşenin içeriği SEO açısından kritikse, alternatif çözümler (örneğin, içeriği sunucuda render edip etkileşimi istemcide canlandırmak) düşünmelisiniz. Genellikle, sadece etkileşimli veya görsel elementler için kullanılır, kritik metinsel içerik için değil.
-
Performans: Sunucu tarafındaki yükü azaltır, ancak istemci tarafında ekstra bir render adımı ekler. Yüklenecek bileşen büyük veya karmaşıksa, ilk sayfa yüklemesinden sonra bir miktar gecikme veya “flicker” (kısa süreli yanıp sönme) yaşanabilir.
ssr-placeholder kullanarak bu etkiyi azaltabilirsiniz.
Kullanıcı Deneyimi
ile sarmalanan bileşenlerin ilk yüklemede görünmemesi, kullanıcı deneyimini olumsuz etkileyebilir. Bu durumu iyileştirmek için:
-
Placeholder Kullanımı:
ssr-placeholder prop’unu kullanarak bileşenin yüklendiğini belirten bir metin, bir iskelet yükleyici veya basit bir spinner gösterebilirsiniz. Bu, kullanıcının boş bir alan yerine bir beklenti içinde olmasını sağlar.
-
Minimum Boyutlandırma: Placeholder’a, yüklenecek bileşenin tahmini boyutlarına uygun bir yükseklik ve genişlik vererek layout shift (düzen kayması) sorununu en aza indirin.
Alternatif Yaklaşımlar
vue-no-ssr basit ve etkili bir çözüm olsa da, bazı durumlarda daha gelişmiş alternatifler düşünebilirsiniz:
v-if="mounted"
Basit durumlar için, bileşenin mounted hook’unda bir flag ayarlayıp v-if ile render etmeyi kontrol edebilirsiniz:
Bu yaklaşım, vue-no-ssr‘a benzer bir etki yaratır ancak sunucuda herhangi bir placeholder render etmez. Sadece boş bir alan bırakır ve istemcide bileşen yüklendiğinde görünür hale gelir.
Dinamik İçe Aktarma (Dynamic Imports)
Daha büyük veya daha az kullanılan bileşenler için, bunları sadece ihtiyaç duyulduğunda veya istemci tarafında dinamik olarak içe aktarmak performans açısından faydalı olabilir. Bu, Vue’nun defineAsyncComponent özelliği ile birleştirilebilir:
// components/MyHeavyChart.vue
// Bu bileşen tarayıcıya özgü kod içeriyor
// App.vue
Nuxt.js gibi çerçevelerde bu durum daha da kolaylaştırılmıştır.
Nuxt.js’in Bileşeni
Eğer Nuxt.js kullanıyorsanız, vue-no-ssr‘a benzer ve hatta daha gelişmiş bir yerleşik bileşen olan mevcuttur. Nuxt.js projesinde vue-no-ssr yerine kullanmanız şiddetle tavsiye edilir:
, Nuxt.js’in hidrasyon mekanizmasıyla daha entegre çalışır ve vue-no-ssr‘ın sunduğu tüm özellikleri (placeholder dahil) sağlar.
Sonuç ve Sıkça Sorulan Sorular (SSS)
vue-no-ssr, Vue.js uygulamalarında Sunucu Tarafı Render (SSR) kullanırken karşılaşılan yaygın bir soruna, yani tarayıcıya özgü API’lere bağımlı bileşenlerin sunucuda hata vermesi sorununa basit ve etkili bir çözüm sunar. Bu kütüphane sayesinde, uygulamanızın genel SSR yeteneklerini koruyabilir ve sadece belirli bileşenleri istemci tarafında yükleyerek hem geliştirme sürecinizi kolaylaştırabilir hem de kullanıcı deneyimini iyileştirebilirsiniz.
Ancak, her araç gibi vue-no-ssr‘ın da kendi kullanım alanları ve dikkat edilmesi gereken noktaları vardır. SEO, performans ve kullanıcı deneyimi üzerindeki potansiyel etkilerini göz önünde bulundurarak bilinçli kararlar vermek önemlidir.
Sıkça Sorulan Sorular (SSS)
vue-no-ssr SEO’yu etkiler mi?
Evet, içinde sarmalanan içerik, ilk HTML çıktısında sunucudan gelmediği için arama motoru botları tarafından doğrudan indekslenmeyebilir. Eğer bu içeriğin SEO açısından kritik olduğunu düşünüyorsanız, farklı bir yaklaşım (örneğin, içeriği sunucuda render edip etkileşimi istemcide canlandırmak) düşünmelisiniz.
Her bileşende vue-no-ssr kullanmalı mıyım?
Hayır, sadece tarayıcıya özgü API’lere bağımlı olan veya sunucuda hata veren bileşenler için kullanmalısınız. Gereksiz yere kullanmak, uygulamanızın SSR avantajlarını azaltabilir ve istemci tarafı yükünü artırabilir.
Nuxt.js kullanıyorum, yine de vue-no-ssr‘a ihtiyacım var mı?
Nuxt.js kullanıyorsanız, yerleşik bileşenini kullanmanız önerilir. Bu bileşen, Nuxt.js’in kendi hidrasyon mekanizmasıyla daha uyumlu çalışır ve vue-no-ssr‘ın sunduğu tüm özellikleri sağlar.
vue-no-ssr‘ın alternatifleri nelerdir?
Basit durumlar için v-if="mounted" kullanabilir, daha karmaşık senaryolar için dinamik içe aktarmayı (defineAsyncComponent ile) düşünebilirsiniz. Nuxt.js kullanıcıları için en iyi alternatiftir.
vue-no-ssr kullanmak uygulamanın performansına nasıl etki eder?
Sunucu tarafındaki render yükünü azaltarak sunucu performansını artırır. Ancak, sarmalanan bileşenlerin istemcide yüklenmesi ve render edilmesi gerektiği için, ilk sayfa yüklemesinden sonra istemci tarafında bir miktar gecikme veya DOM manipülasyonu yaşanabilir. Bu etkiyi ssr-placeholder ile minimize edebilirsiniz.
