İlk store

Kurulum

React rehberindeki gibi bir Vite projesi açın ve paketi ekleyin:¹

$ pnpm add zustand

Paket React 18 ve sonrasıyla çalışır. Ek bir Provider ya da kurulum dosyası gerekmez.²

create ile Store

Store'u create ile oluşturursunuz. Fonksiyon bir hook döndürür. İçine state'i ve onu değiştiren fonksiyonları (action) birlikte koyarsınız:¹³

// src/features/cart/cart-store.ts
import { create } from "zustand";

type CartItem = { id: number; name: string; price: number; quantity: number };

type CartState = {
  items: CartItem[];
  isOpen: boolean;
  addItem: (item: Omit<CartItem, "quantity">) => void;
  toggle: () => void;
  clear: () => void;
};

export const useCartStore = create<CartState>()((set) => ({
  items: [],
  isOpen: false,
  addItem: (item) =>
    set((state) => ({ items: [...state.items, { ...item, quantity: 1 }] })),
  toggle: () => set((state) => ({ isOpen: !state.isOpen })),
  clear: () => set({ items: [] }),
}));

TypeScript'te create(...) yerine create<CartState>()(...) yazılır. Fazladan () bilinçlidir: TypeScript, set ve get aynı tipi hem alıp hem verdiği için state tipini kendisi çıkaramaz. Curried yazım tipi elle vermenizi sağlarken middleware'lerin tiplerini çıkarmaya devam eder.⁴

Dosya adı ve yeri için genel kural: store'u kullanan özelliğin klasörüne koyun (bkz. Component ve Kod Organizasyonu).

Component'te Kullanmak

Hook'a bir selector verirsiniz. Component yalnızca selector'ın döndürdüğü değer değiştiğinde render olur:¹

function CartBadge() {
  const count = useCartStore((state) => state.items.length);
  return <span>{count}</span>;
}

function AddButton() {
  const addItem = useCartStore((state) => state.addItem);
  return (
    <button onClick={() => addItem({ id: 1, name: "Canvas Sneaker", price: 1200 })}>
      Sepete ekle
    </button>
  );
}

AddButton yalnızca addItem'ı okur. Action'lar hiç değişmediği için sepete ürün eklendiğinde bu buton render olmaz. Selector'ların ayrıntısı Selector ve yeniden render dersinde.

set: Birleştirerek Günceller

set'e verdiğiniz nesne mevcut state ile birleştirilir; yalnızca verdiğiniz alanlar değişir. Önceki state'e göre güncellerken fonksiyon verin.³⁵

set({ items: [] }); // isOpen ve action'lar olduğu gibi kalır
set((state) => ({ isOpen: !state.isOpen })); // önceki değere göre

Birleştirme yalnızca bir seviye derindir. İç içe bir nesneyi güncellerken onu kendiniz kopyalamalısınız:⁵

type ProfileState = {
  user: { name: string; theme: "light" | "dark" };
  setTheme: (theme: "light" | "dark") => void;
};

const useProfileStore = create<ProfileState>()((set) => ({
  user: { name: "Ada", theme: "light" },
  // ❌ set({ user: { theme } }) name alanını siler
  setTheme: (theme) => set((state) => ({ user: { ...state.user, theme } })),
}));

State'i değiştirmeyin, yeni değer döndürün. state.items.push(item) yazmak store'u değiştirir ama aboneler haberdar olmaz; ekran güncellenmez.⁵ React'teki kural aynıdır (bkz. State).

set'in ikinci argümanı true olursa state birleştirilmez, değiştirilir. v5'te bu durumda TypeScript tam bir state ister; eksik alan verirseniz derlenmez.² Action'ları da sileceği için nadiren gerekir.

get ve Async Action

create'e verdiğiniz fonksiyonun ikinci parametresi get'tir; action içinde güncel state'i okur. Action'lar async olabilir; Zustand için fark etmez, iş bitince set çağırırsınız:⁴

type CouponState = {
  code: string | null;
  discount: number;
  applyCoupon: (code: string) => Promise<void>;
};

const useCouponStore = create<CouponState>()((set, get) => ({
  code: null,
  discount: 0,
  applyCoupon: async (code) => {
    if (get().code === code) return;
    const { discount } = await validateCoupon(code);
    set({ code, discount });
  },
}));

React Dışından Erişmek

Hook aynı zamanda store'un kendisidir. Üzerindeki fonksiyonlarla state'i React dışından okuyup değiştirebilirsiniz:⁶

// Bir WebSocket mesajında
socket.on("cart-cleared", () => useCartStore.setState({ items: [] }));

const unsubscribe = useCartStore.subscribe((state, prevState) => {
  if (state.items.length !== prevState.items.length) {
    analytics.track("cart_changed", { count: state.items.length });
  }
});

Component içinde useCartStore.getState() ile değer okumayın; abone olmadığınız için değer değişince component güncellenmez. Event handler içinde güncel değeri okumak için kullanabilirsiniz.

Tip Yazmadan: combine

State tipini ayrıca yazmak istemiyorsanız combine middleware'i ilk state'ten tipi çıkarır. Bu durumda curried yazım gerekmez:⁴

import { create, type ExtractState } from "zustand";
import { combine } from "zustand/middleware";

export const useCounterStore = create(
  combine({ count: 0 }, (set) => ({
    increase: () => set((state) => ({ count: state.count + 1 })),
  })),
);

export type CounterState = ExtractState<typeof useCounterStore>;

Bedeli küçük bir tip açığıdır: action'ların içindeki get ve set yalnızca ilk state'i bilir, action'ları görmez. Dokümanın notu: çoğu durumda sorun çıkarmaz, set(..., true) ile değiştirirken dikkat edin.⁴ ExtractState, store'un tam tipini testlerde ve yardımcı fonksiyonlarda kullanmak için verilir.⁷

Kendin Dene

• Sepet store'unu kurun. CartBadge ve AddButton'a console.log("render") koyun; ürün eklerken hangisi loglanıyor?

• addItem'ı state.items.push(...) ile yazın. Ekran güncelleniyor mu? getState().items ne diyor?

• Tarayıcı konsolunda store'u window'a bağlayıp setState({ isOpen: true }) çağırın; ekran güncelleniyor mu?

• set({ isOpen: true }, true) yazın. TypeScript ne diyor?

Detaylı Öğrenmek İçin

• Resmi doküman: "Beginner TypeScript Guide"; tipli store, ExtractState, sıfırlama ve birden fazla store.⁷

• Resmi doküman: "Advanced TypeScript Guide"; curried yazımın ve tip çıkarımının nedeni.⁴

• Resmi doküman: "Updating state"; düz ve iç içe güncellemeler.⁵