Pinia'yı Anlamak: Vue.js Uygulamalarında State Management

Güncel Vue.js projelerindeki state yönetimi, resmi kütüphane olan Pinia ile yapılmaktadır. 

Bu makalede, Pinia'nın yeteneklerinden ve Vue projelerine nasıl entegre edileceğinden bahsedilecektir.

Pinia Nedir?

Pinia, Vue.js uygulamalarında global state’i yönetmek için kullanılan, Vue 3 ile tam uyumlu, modern ve hafif bir state management çözümüdür.

Pinia, Vue.js çekirdek ekibi tarafından geliştirilen bir state, store management kütüphanesidir. Açık kaynaklıdır. Repo linki için tıklayınız. 

Vuex ile aynı amaca sahiptir.

Pinia'nın Kahramanı Ananas

Pinia, İspanyolca'da ananas demektir. Ananas aslında, bir araya gelerek çoklu bir meyve oluşturan ayrı ayrı çiçeklerin bir araya gelmesinden oluşur. Store yapısının çalışma mantığı da ananasların oluşmasına benzer, her biri ayrı ayrı doğar, ancak sonunda hepsi birbirine bağlıdır. Ayrıca Güney Amerika'ya özgü lezzetli bir tropikal meyvedir.

Bu analojiyi anladıysak teknik konuya değinebiliriz. 

Vue.js State Management

Vue.js ile projelerinde veri yönetimi componentler arasında gerçekleşir. Verilerin taşınması ve manipülasyonu önemli bir aşamadır ve sürecin iyi bir şekilde yönetilmesi gerekmektedir.

Projenin ölçeği büyüdüğünde bu süreç karmaşık bir hal alabilir. 

Props - Emits Yapıları

Props Emits Veri Akışı

Componentler arası veri akışı, props ve emits yapıları ile yönetilmektedir. 

Parent(üst) component'ten Child(alt) componente veri taşınması "props" yapısıyla, tam tersi yöndeki veri akışı da eventler ile emits yapılarıyla gerçekleşmektedir. Her component'in kendi statelerini yönetmesi durumu da olduğu için proje büyüdükçe veri akışı ve iletişimini yönetmek karmaşık hale gelecektir. 

Global State ile Pinia'nın Devreye Girmesi

Pinia'nın sunduğu Global State yapısı ile veriler merkezi olarak yönetilmektedir. Global state yönetimi sayesinde birden fazla component aynı veri kaynağını paylaşıp, reaktif olarak güncelleyebilir.

Global State Yapısı

Not: Projedeki iş kurallarına göre Pinia kullanılırken props ve emit yapıları kullanılabilir. 

Pinia vs Vuex Karşılaştırılması

Aynı amaca hizmet eden bu iki kütüphanenin karşılaştırılması konusunda, aşağıdaki konularla yavaş yavaş Pinia'yı tanımaya ve Vuex'in de eksikliklerine değineceğiz.   

  • Pinia, Vue 3 için resmi state management çözümüyken, Vuex bakım modundadır, Vuex artık yeni güncellemeler sunmayacaktır.
  • Pinia'nın indirme ve kullanım sayısı artış eğilimindedir.
  • Pinia, Vuex’e göre daha az eğitim ve teknik makaleye sahiptir. Buna rağmen dokümantasyonu kullanışlıdır.
  • Vuex’ten Pinia’ya migration gerektirir. Klasör yapısı, store yapısı ve çağrılması farklı olduğundan değişiklik gerektirir.
  • Pinia, Composition API ile uyumlu çalışır.
  • Pinia, daha az boilerplate (şablon kod) gerektirir. Vuex, daha ayrıntılıdır.
  • State verisinin güncellenmesi için Vuex, action ve state arasında mutations yapısını kullanırken Pinia, state güncellemesi için sadece actions yapısını kullanır.
  • Pinia, hot reload değişikliği destekler. Değişikliğin yansıması için sayfanın yenilenmesine gerek duymayacaktır.

Store Syntax Farklılığı

Soldaki kod bloğu, Vuex'in store şablonuna aittir. Vuex'te actions yapısı içerisindeki fonksiyonlarda commit fonksiyonu üzerinden ilgili mutasyona bağlanır ve state değişikliği de o alanda gerçekleşir.

Pinia'ya göre (Sağdaki kod bloğu) daha fazla kod bloğuna sahiptir. State ve Getters tanımları neredeyse aynı şekilde oluşturulmaktadır. Görselde de görüldüğü gibi, mutation tanımı olmadan state doğrudan action içinde güncellenebiliyor. Böylece basitlik sağlar. 

Vuex vs Pinia

Klasör Yapıları

Vuex için store klasörü altında index.js dosyasında birden çok store bulunur ve iç içe modüller arasında import yapılır. namespace klasörleme mantığı olarak da düşünülebilir.

Vuex - Klasör yapısı

Pinia için birden fazla store oluşturulup stores klasörü altında konumlandırılır. Pinia'da her dosya kendi başına bir modüldür, bu yüzden karmaşık nested modules ve namespacing yapılarına ihtiyaç duyulmaz.

Pinia - Klasör yapısı

Pinia'nın Öne Çıkan Özellikleri

Bu bölüm, neden Vuex yerine Pinia tercih etmeniz gerektiğinin cevaplarını anlayacağınız kısım olacaktır. 

Hafiflik, Devtools desteği, modüler tasarım, kolay öğrenilebilirlik, genişletilebilirlik ve tip güvenliği konularında güçlü yönleri bulunmaktadır. Gelin bu özelliklerin detayını anlayalım.

Pinia'nın öne çıkan özellikleri

Intuitive - Öğrenme Kolaylığı

Pinia'daki store yapısı görünüm olarak component yapısına benzer, Vuex'e göre öğrenme eğrisi düşüktür, kolay öğrenilen bir kütüphanedir. Store oluşturmak, component oluşturmak kadar kolaydır.

Hafiflik

Pinia, tasarımı gereğince boyutu küçüktür. İndirme boyutu, kilobayt seviyesinde ifade ediliyor. (Yaklaşık 1-1.5 kB). Performans, verimlilik ve yükleme açısından avantaj sağlamaktadır. 

Devtools Desteği

Google Chrome ile çalışırken Vue eklentisini kurduktan sonra Pinia sekmesine ulaşırsınız. Basit bir arayüz sunar. Componentlerde kullanılan store, state, getters gibi temel yapı taşlarındaki değerleri gösterir. Timeline bölümünde ise state güncellenmesi, event performansı gibi temel metrikleri gösterir.

Devtools - Vue Eklentisi Arayüzü

Tip Güvenliği

Vuex'e göre güçlü bir TypeScript desteği sunar. Auto inference özelliğinden dolayı tip çıkarımını yapabilmesi kolaydır. Manuel bir şekilde her bir tip için yeni bir tanım yapmaya gerek yoktur. 

Modüler Tasarım

Gerektiğinde farklı componentler tarafından import edilebilen küçük ve bağımsız "store" yapıları oluşturma imkanı sunar. Böylece kodları bölme, yönetme ve organizasyonunu kolaylaştırır.

Extensible

Store yapısı üzerinde kendi plugin yapısını oluşturabiliriz. Ayrıca uygulama business yapısını etkilemeyen fakat uygulama mimarisine göre yan özellikler eklenmesini sağlayan "Cross Cutting Concern"lerle store yapıları genişletilebilir. Local storage, API Cache, Feature Flag, Authorization süreci bu özelliklere örnektir.

Mevcut veya Yeni Proje Geliştirirken Pinia'yı Tercih Etmek

Yeni bir Vue projesi geliştirilecekse; Evet, Pinia kullanılmalıdır. Daha modern, daha sade, Vue 3 ile uyumlu bir proje geliştirilmiş olursunuz.

Mevcut projelerde çalışıp Vuex kullanılıyorsa proje sürecine göre karar verilmelidir. 

Eğer yeni özellikler eklenmeye devam edilip aktif geliştirme yapılıyorsa; mimariyi yenilemek amaçlı olarak Pinia'ya geçmeyi düşünebilirsiniz.

Eğer sadece bakım yapılıyorsa ve yeni geliştirme neredeyse yoksa; Pinia'ya geçmek şart değildir. Canlı projelerde, Vuex'ten Pinia'ya geçiş için harcanan efor ve zaman fazla olmaktadır.

Pinia Kurulumu

İster yeni bir projede ister mevcut bir proje için Pinia kolaylıkla dahil edilebilir. 

Yeni bir proje oluşturulurken, aşağıdaki görseldeki gibi vite ve vue işbirliği ile yapılandırma ayarlarında state management kütüphanesi olarak Pinia seçeneği gelmektedir. Seçilip kurulum tamamlandığında Vue projesinde pinia kullanılabilen bir yapı oluşturulacaktır.

vite + vue kurulum aşaması

Mevcut bir projeye pinia dahil edilecekse; npm install pinia diyerek saniyeler içerisinde son versiyon kurulacaktır.
npm install pinia

pinia kurulum sonucu

Kurulum tamamlandıktan sonra Vue projesindeki temel dosyalardan birisi ve Vue componentlerinin ana div elementine montelenmesinin yapıldığı yer olan main.js'e (sıradaki görsel) createPinia fonksiyonu ile app.use fonksiyonuna parametre geçilerek Pinia kullanıma hazır duruma gelmiştir. 

main.js pinia kurulumu

Pinia'nın Temel Konseptleri

Pinia'daki store yapısı; state, getters ve actions yapılarını tutan bloklardır.

Store Oluşturma Aşaması

Bir pinia store oluşturulurken defineStore fonksiyonu kullanılır. Fonksiyonun ilk parametresi, tekil bir isim olacak id parametresidir. Sonraki parametre state, actions ve getters yapılarını barındıran bir yapılandırma bloğudur. 

En iyi kullanım pratiği olarak; tekil bir isim olarak verilen id parametresi use ve Store ile sarmallanarak farklı componentlerin kullanabileceği bir store değişkenine dönüştürülür.

Örneğin; aşağıdaki görselde bulunan counter ismine sahip bir store; useCounterStore ismi ile dışarıdan çağrılır ve state, actions ve getters yapılarına erişir. 


Pinia store yapısı Setup ve Options store olmak üzere iki türlüdür. 

Setup Store; Vue Composition API mantığına benzer. Karmaşık iş kuralları varsa tercih edilebilir. ref, reactive yapılarının doğrudan kullanılmasına imkan tanır. Generic kullanım için güçlüdür ve karmaşık tipler için daha doğaldır. return keywordü ile farklı componentler tarafından kullanılacak state ve actions yapılarını obje olarak döndürür. 

Setup Store

Option Store; Vue Options API mantığına benzer. Basit CRUD işlemleri ve state yönetimi için kullanışlıdır. Setup store yapılarına göre fazla esnek değildir. state / getters / actions bölümleri nettir. Ekiplerde farklı bilgi seviyesi varsa option store daha güvenlidir. 

Option Store

Store Bileşenleri - State, Getters, Actions

Options Store'de belirgin olarak ifade edilen store bileşenleri olan state, getters ve action yapılarına kısaca değinelim. 

Store Bileşenleri

State

Uygulamadaki componentler tarafından kullanılan veya değiştirilebilen veri birimidir. Reaktiftir yani state değeri değiştiğinde; bütün componentler güncel değerden haberdar olacaktır. 

State tanımlaması - useCounterStore

count değeri 0 olan bir state değişkeni oluşturuldu. Genellikle başlangıç değeri olarak ayarlanan değerler, bu blokta tanımlanır.

Getters

Statelerdeki alanlardan hesaplanıp türetilen değerleri barındırır. Veri yönetimi ve erişimi açısından faydalıdır. State değerindeki değişiklikler sonrasında oluşturulan getters tanımı da değişir. Başka store içerisindeki getters yapıları tarafından da ulaşılabilir.

Getter tanımı - doubleCount -  useCounterStore

Yukarıdaki örnek kod bloğunda; state nesnesindeki count propertysi değiştiğinde; iki katı değerini hesaplayıp getter değeri olarak dönen doubleCount property oluşturulmuştur. 

Actions

İş kurallarının tanımlandığı fonksiyonların bulunduğu bloklardır. Dış servislere bağlanıp sonuç üretebildiği gibi, mutasyon süreci olmadan state değerlerinin doğrudan değiştirilmesini sağlar. Asenkron çağrılar yapan fonksiyonlar oluşturulabilir.

Actions - increment/decrement -  useCounterStore

Yukarıdaki örnek kod bloğunda; count değerinin bir arttırılması için increment, bir azaltılması için de decrement fonksiyonu oluşturulmuştur. Vuex yapısındaki mutations yapısı olmadan doğrudan count statesine erişerek değeri güncellenebilmektedir.

Component içerisinde store kullanımı

counter.js store dosyasından useCounterStore değişkeni import edildikten sonra, store isimli değişkene store atanmıştır. State, getters ve actions yapısından ihtiyaç olan yapıyı bu değişken üzerinden kullanabilirsiniz.

Hot Reload Özelliği Kurulması 

Store’de yapılan değişikliği sayfayı yenilemeye gerek kalmadan doğrudan tarayıcıya yansıtılmasını sağlayan bir mekanizmadır. Hot Module Replacement (HMR) özelliği, Pinia'nın acceptHMRUpdate fonksiyonu ile gelmektedir. 
Store dosyası içerisinde ilgili store değişkenini acceptHMRUpdate fonksyionuna parametre olarak vererek değişikliği algılayıp otomatik olarak sayfaya yansıtmasını sağlar. 

if bloğu ile değişiklik olup olmadığını kontrol ettikten sonra fonksiyon çalışır. 

HMR kullanımı

Özetle; 

🏆 Pinia Kazanır!

  • Pinia, Vuex'in yerini alan resmi Vue state management kütüphanesi,
  • Kb seviyesinde paket yükleme boyutu,
  • Daha iyi TypeScript desteği,
  • State değişikliklerinde mutasyon gerektirmemesi,
  • Composition API entegrasyonu,
  • Devtools desteği,
  • Kullanımın yaygınlaşması

konuları, Pinia'nın güncel Vue projeleriyle neden kullanılması gerektiğini ortaya koymaktadır.

Bonus Video

19 Aralık 2025 tarihinde İstanbul Javascript Topluluğu ile düzenlediğimiz "Pinia'yı Anlamak: Vue.js Uygulamalarında State Management" konulu etkinlikte Youtube videosu üzerinden örnek kod gösterimleriyle konuyu anlattım. 

Youtube linki için tıklayınız. 

Örneklerin olduğu github reposu için tıklayınız. 

Yazının faydalı olmasını umarak, çalışmalarınızda kolaylıklar diliyorum :)

Kaynaklar

Pinia Resmi Dokümantasyonu: https://pinia.vuejs.org/

Yorumlar

Yorum Gönder