Persist Middleware

Q: Qual é a configuração mínima necessária para usar o middleware persist?

Apenas a opção name (a chave do localStorage) é necessária.

Q: O que partialize faz e por que usá-lo?

partialize controla quais propriedades do estado são salvas no armazenamento. Por padrão, todo o estado (incluindo funções) é serializado. Sempre use-o para excluir ações e valores não serializáveis.

Q: Como lidar com migrações de esquema quando a forma do estado persistido muda?

Defina um número de version na configuração do persist. Forneça uma função migrate que transforma o estado antigo para a nova forma. migrate é executada quando a versão armazenada é menor que a versão atual.

Q: Como usar um motor de armazenamento personalizado como IndexedDB?

Implemente a interface StateStorage (getItem, setItem, removeItem). Envolva-a com createJSONStorage(() => yourStorage). Isso suporta motores de armazenamento síncronos e assíncronos.

Q: Como esperar pela hidratação antes de renderizar em um aplicativo Next.js?

Use useAppStore.persist.onFinishHydration() em um useEffect para definir um sinalizador hydrated. Verifique useAppStore.persist.hasHydrated() para verificações síncronas. Renderize um estado de carregamento até que a hidratação seja concluída.

Q: Que tipo a função migrate recebe em TypeScript?

migrate recebe unknown para o estado persistido e um number para a versão. Você deve fazer o cast com cuidado: const state = persisted as Partial.

Receita

Use o middleware persist para salvar e restaurar automaticamente o estado do store no localStorage, sessionStorage ou qualquer motor de armazenamento personalizado.

import { create } from "zustand";
import { persist } from "zustand/middleware";
 
interface PreferencesStore {
  language: string;
  currency: string;
  setLanguage: (lang: string) => void;
  setCurrency: (currency: string) => void;
}
 
export const usePreferencesStore = create<PreferencesStore>()(
  persist(
    (set) => ({
      language: "en",
      currency: "USD",
      setLanguage: (language) => set({ language }),
      setCurrency: (currency) => set({ currency }),
    }),
    {
      name: "user-preferences", // chave do localStorage
    }
  )
);

Exemplo de Trabalho

// stores/app-store.ts
import { create } from "zustand";
import { persist, createJSONStorage, StateStorage } from "zustand/middleware";
 
interface AppState {
  user: { name: string; email: string } | null;
  theme: "light" | "dark";
  recentSearches: string[];
  setUser: (user: AppState["user"]) => void;
  setTheme: (theme: AppState["theme"]) => void;
  addSearch: (query: string) => void;
  clearSearches: () => void;
}
 
// Motor de armazenamento personalizado via IndexedDB com idb-keyval
const indexedDBStorage: StateStorage = {
  getItem: async (name) => {
    const { get } = await import("idb-keyval");
    return (await get(name)) || null;
  },
  setItem: async (name, value) => {
    const { set } = await import("idb-keyval");
    await set(name, value);
  },
  removeItem: async (name) => {
    const { del } = await import("idb-keyval");
    await del(name);
  },
};
 
export const useAppStore = create<AppState>()(
  persist(
    (set) => ({
      user: null,
      theme: "light",
      recentSearches: [],
 
      setUser: (user) => set({ user }),
      setTheme: (theme) => set({ theme }),
 
      addSearch: (query) =>
        set((state) => ({
          recentSearches: [
            query,
            ...state.recentSearches.filter((s) => s !== query),
          ].slice(0, 10),
        })),
 
      clearSearches: () => set({ recentSearches: [] }),
    }),
    {
      name: "app-storage",
      storage: createJSONStorage(() => indexedDBStorage),
      partialize: (state) => ({
        theme: state.theme,
        recentSearches: state.recentSearches,
        // Excluir usuário - buscar novamente da API no carregamento
      }),
      version: 2,
      migrate: (persistedState: any, version) => {
        if (version === 0) {
          // v0 tinha "darkMode: boolean" em vez de "theme"
          persistedState.theme = persistedState.darkMode ? "dark" : "light";
          delete persistedState.darkMode;
        }
        if (version < 2) {
          // v1 tinha "searches" em vez de "recentSearches"
          persistedState.recentSearches = persistedState.searches || [];
          delete persistedState.searches;
        }
        return persistedState;
      },
    }
  )
);

// components/hydration-gate.tsx
"use client";
 
import { useEffect, useState } from "react";
import { useAppStore } from "@/stores/app-store";
 
export function HydrationGate({ children }: { children: React.ReactNode }) {
  const [hydrated, setHydrated] = useState(false);
 
  useEffect(() => {
    // Esperar pela reidratação do persist
    const unsub = useAppStore.persist.onFinishHydration(() => {
      setHydrated(true);
    });
 
    // Se já hidratado
    if (useAppStore.persist.hasHydrated()) {
      setHydrated(true);
    }
 
    return unsub;
  }, []);
 
  if (!hydrated) return <div>Carregando...</div>;
  return <>{children}</>;
}

Mergulho Profundo

Como Funciona

O middleware persist intercepta cada chamada set e escreve o novo estado no armazenamento após a atualização do estado.
Na criação do store, persist lê do armazenamento e mescla o estado persistido com o estado padrão.
partialize controla quais propriedades do estado são salvas. Por padrão, todo o estado (incluindo funções) é serializado.
version e migrate permitem a evolução do esquema. Quando a versão armazenada é menor que a versão atual, migrate transforma o estado antigo.
createJSONStorage envolve uma interface StateStorage com serialização e desserialização JSON.
A hidratação é assíncrona. O estado começa com os padrões, depois atualiza assim que o armazenamento é lido.

Variações

sessionStorage:

import { createJSONStorage } from "zustand/middleware";
 
persist(storeCreator, {
  name: "session-store",
  storage: createJSONStorage(() => sessionStorage),
});

Persistência seletiva com merge:

persist(storeCreator, {
  name: "store",
  partialize: (state) => ({ theme: state.theme, lang: state.lang }),
  merge: (persistedState, currentState) => ({
    ...currentState,
    ...(persistedState as Partial<State>),
  }),
});

Armazenamento criptografado:

const encryptedStorage: StateStorage = {
  getItem: (name) => {
    const raw = localStorage.getItem(name);
    if (!raw) return null;
    return decrypt(raw);
  },
  setItem: (name, value) => {
    localStorage.setItem(name, encrypt(value));
  },
  removeItem: (name) => {
    localStorage.removeItem(name);
  },
};

Limpar dados persistidos:

// Limpar programaticamente o estado persistido
useAppStore.persist.clearStorage();
 
// Ou manualmente
localStorage.removeItem("app-storage");

Notas de TypeScript

O middleware persist preserva a assinatura de tipo do store.
partialize deve retornar um tipo parcial seguro. Use Pick<State, keys> para tipagem explícita.
migrate recebe unknown para o estado persistido. Faça o cast com cuidado.

persist<AppState>(storeCreator, {
  name: "store",
  partialize: (state): Pick<AppState, "theme" | "language"> => ({
    theme: state.theme,
    language: state.language,
  }),
  migrate: (persisted: unknown, version: number) => {
    const state = persisted as Partial<AppState>;
    return state as AppState;
  },
});

Armadilhas

A hidratação é assíncrona. Os componentes podem renderizar brevemente com o estado padrão antes que o estado persistido seja carregado. Use onFinishHydration ou hasHydrated() para controlar a renderização.
Funções no estado são serializadas como null por JSON.stringify. Sempre use partialize para excluir ações, ou elas serão perdidas e substituídas pelos padrões na reidratação.
O localStorage tem um limite de ~5MB por origem. Stores grandes podem falhar silenciosamente ao persistir. Monitore o uso do armazenamento.
version tem o valor padrão 0. Se você não definir uma versão e precisar de migrações posteriormente, deve começar da versão 0 em sua função migrate.
O HTML renderizado no servidor usa o estado padrão. Se o estado persistido for diferente (por exemplo, tema escuro), haverá um flash de conteúdo incorreto. Lide com isso usando um portão de hidratação ou detecção de tema baseada em CSS.
Múltiplas abas podem sobrescrever o estado persistido umas das outras. A última aba a escrever vence. Considere o evento storage para sincronização entre abas.

Alternativas

Abordagem	Prós	Contras
localStorage (padrão)	Leitura simples e síncrona	Limite de 5MB, bloqueia a thread principal
sessionStorage	Limpa automaticamente ao fechar a aba	Não compartilhado entre abas
IndexedDB	Grande capacidade, assíncrono	Configuração mais complexa
Armazenamento de Cookie	Disponível no servidor (SSR)	Limite de 4KB, enviado com cada requisição

FAQs

Qual é a configuração mínima necessária para usar o middleware persist?

import { persist } from "zustand/middleware";
 
create<MyState>()(
  persist(storeCreator, { name: "storage-key" })
);

Apenas a opção name (a chave do localStorage) é necessária.

Como funciona a hidratação e por que ela causa um breve flash de estado padrão?

Persist lê do armazenamento de forma assíncrona após a criação do store.
Os componentes inicialmente renderizam com o estado padrão, depois atualizam assim que o estado persistido é carregado.
Use onFinishHydration ou hasHydrated() para controlar a renderização até que a hidratação seja concluída.

O que `partialize` faz e por que usá-lo?

partialize controla quais propriedades do estado são salvas no armazenamento.
Por padrão, todo o estado (incluindo funções) é serializado.
Sempre use-o para excluir ações e valores não serializáveis.

Como lidar com migrações de esquema quando a forma do estado persistido muda?

Defina um número de version na configuração do persist.
Forneça uma função migrate que transforma o estado antigo para a nova forma.
migrate é executada quando a versão armazenada é menor que a versão atual.

Como usar um motor de armazenamento personalizado como IndexedDB?

Implemente a interface StateStorage (getItem, setItem, removeItem).
Envolva-a com createJSONStorage(() => yourStorage).
Isso suporta motores de armazenamento síncronos e assíncronos.

Armadilha: O que acontece se o localStorage exceder seu limite de ~5MB?

A escrita falha silenciosamente. O estado não é persistido.
Monitore o uso do armazenamento para stores grandes ou use IndexedDB para maior capacidade.

Armadilha: Múltiplas abas podem sobrescrever o estado persistido umas das outras?

Sim. A última aba a escrever vence.
Considere ouvir o evento storage para sincronização entre abas.
Não há sincronização integrada entre abas no middleware persist do Zustand.

Como limpar programaticamente os dados persistidos?

useAppStore.persist.clearStorage();
// Ou manualmente:
localStorage.removeItem("app-storage");

Como esperar pela hidratação antes de renderizar em um aplicativo Next.js?

Use useAppStore.persist.onFinishHydration() em um useEffect para definir um sinalizador hydrated.
Verifique useAppStore.persist.hasHydrated() para verificações síncronas.
Renderize um estado de carregamento até que a hidratação seja concluída.

Como tipar a opção `partialize` em TypeScript?

persist<AppState>(storeCreator, {
  name: "store",
  partialize: (state): Pick<AppState, "theme" | "language"> => ({
    theme: state.theme,
    language: state.language,
  }),
});

Que tipo a função `migrate` recebe em TypeScript?

migrate recebe unknown para o estado persistido e um number para a versão.
Você deve fazer o cast com cuidado: const state = persisted as Partial<AppState>.

Qual a diferença entre localStorage e sessionStorage para persist?

localStorage persiste entre sessões e abas do navegador.
sessionStorage é limpo quando a aba é fechada e não é compartilhado entre abas.
Alterne passando createJSONStorage(() => sessionStorage) como a opção storage.

Links Relacionados

Receita

Use o middleware persist para salvar e restaurar automaticamente o estado do store no localStorage, sessionStorage ou qualquer motor de armazenamento personalizado.

import { create } from "zustand";
import { persist } from "zustand/middleware";
 
interface PreferencesStore {
  language: string;
  currency: string;
  setLanguage: (lang: string) => void;
  setCurrency: (currency: string) => void;
}
 
export const usePreferencesStore = create<PreferencesStore>()(
  persist(
    (set) => ({
      language: "en",
      currency: "USD",
      setLanguage: (language) => set({ language }),
      setCurrency: (currency) => set({ currency }),
    }),
    {
      name: "user-preferences", // chave do localStorage
    }
  )
);

Exemplo de Trabalho

// stores/app-store.ts
import { create } from "zustand";
import { persist, createJSONStorage, StateStorage } from "zustand/middleware";
 
interface AppState {
  user: { name: string; email: string } | null;
  theme: "light" | "dark";
  recentSearches: string[];
  setUser: (user: AppState["user"]) => void;
  setTheme: (theme: AppState["theme"]) => void;
  addSearch: (query: string) => void;
  clearSearches: () => void;
}
 
// Motor de armazenamento personalizado via IndexedDB com idb-keyval
const indexedDBStorage: StateStorage = {
  getItem: async (name) => {
    const { get } = await import("idb-keyval");
    return (await get(name)) || null;
  },
  setItem: async (name, value) => {
    const { set } = await import("idb-keyval");
    await set(name, value);
  },
  removeItem: async (name) => {
    const { del } = await import("idb-keyval");
    await del(name);
  },
};
 
export const useAppStore = create<AppState>()(
  persist(
    (set) => ({
      user: null,
      theme: "light",
      recentSearches: [],
 
      setUser: (user) => set({ user }),
      setTheme: (theme) => set({ theme }),
 
      addSearch: (query) =>
        set((state) => ({
          recentSearches: [
            query,
            ...state.recentSearches.filter((s) => s !== query),
          ].slice(0, 10),
        })),
 
      clearSearches: () => set({ recentSearches: [] }),
    }),
    {
      name: "app-storage",
      storage: createJSONStorage(() => indexedDBStorage),
      partialize: (state) => ({
        theme: state.theme,
        recentSearches: state.recentSearches,
        // Excluir usuário - buscar novamente da API no carregamento
      }),
      version: 2,
      migrate: (persistedState: any, version) => {
        if (version === 0) {
          // v0 tinha "darkMode: boolean" em vez de "theme"
          persistedState.theme = persistedState.darkMode ? "dark" : "light";
          delete persistedState.darkMode;
        }
        if (version < 2) {
          // v1 tinha "searches" em vez de "recentSearches"
          persistedState.recentSearches = persistedState.searches || [];
          delete persistedState.searches;
        }
        return persistedState;
      },
    }
  )
);

// components/hydration-gate.tsx
"use client";
 
import { useEffect, useState } from "react";
import { useAppStore } from "@/stores/app-store";
 
export function HydrationGate({ children }: { children: React.ReactNode }) {
  const [hydrated, setHydrated] = useState(false);
 
  useEffect(() => {
    // Esperar pela reidratação do persist
    const unsub = useAppStore.persist.onFinishHydration(() => {
      setHydrated(true);
    });
 
    // Se já hidratado
    if (useAppStore.persist.hasHydrated()) {
      setHydrated(true);
    }
 
    return unsub;
  }, []);
 
  if (!hydrated) return <div>Carregando...</div>;
  return <>{children}</>;
}

Mergulho Profundo

Como Funciona

O middleware persist intercepta cada chamada set e escreve o novo estado no armazenamento após a atualização do estado.
Na criação do store, persist lê do armazenamento e mescla o estado persistido com o estado padrão.
partialize controla quais propriedades do estado são salvas. Por padrão, todo o estado (incluindo funções) é serializado.
version e migrate permitem a evolução do esquema. Quando a versão armazenada é menor que a versão atual, migrate transforma o estado antigo.
createJSONStorage envolve uma interface StateStorage com serialização e desserialização JSON.
A hidratação é assíncrona. O estado começa com os padrões, depois atualiza assim que o armazenamento é lido.

Variações

sessionStorage:

import { createJSONStorage } from "zustand/middleware";
 
persist(storeCreator, {
  name: "session-store",
  storage: createJSONStorage(() => sessionStorage),
});

Persistência seletiva com merge:

persist(storeCreator, {
  name: "store",
  partialize: (state) => ({ theme: state.theme, lang: state.lang }),
  merge: (persistedState, currentState) => ({
    ...currentState,
    ...(persistedState as Partial<State>),
  }),
});

Armazenamento criptografado:

const encryptedStorage: StateStorage = {
  getItem: (name) => {
    const raw = localStorage.getItem(name);
    if (!raw) return null;
    return decrypt(raw);
  },
  setItem: (name, value) => {
    localStorage.setItem(name, encrypt(value));
  },
  removeItem: (name) => {
    localStorage.removeItem(name);
  },
};

Limpar dados persistidos:

// Limpar programaticamente o estado persistido
useAppStore.persist.clearStorage();
 
// Ou manualmente
localStorage.removeItem("app-storage");

Notas de TypeScript

O middleware persist preserva a assinatura de tipo do store.
partialize deve retornar um tipo parcial seguro. Use Pick<State, keys> para tipagem explícita.
migrate recebe unknown para o estado persistido. Faça o cast com cuidado.

persist<AppState>(storeCreator, {
  name: "store",
  partialize: (state): Pick<AppState, "theme" | "language"> => ({
    theme: state.theme,
    language: state.language,
  }),
  migrate: (persisted: unknown, version: number) => {
    const state = persisted as Partial<AppState>;
    return state as AppState;
  },
});

Armadilhas

A hidratação é assíncrona. Os componentes podem renderizar brevemente com o estado padrão antes que o estado persistido seja carregado. Use onFinishHydration ou hasHydrated() para controlar a renderização.
Funções no estado são serializadas como null por JSON.stringify. Sempre use partialize para excluir ações, ou elas serão perdidas e substituídas pelos padrões na reidratação.
O localStorage tem um limite de ~5MB por origem. Stores grandes podem falhar silenciosamente ao persistir. Monitore o uso do armazenamento.
version tem o valor padrão 0. Se você não definir uma versão e precisar de migrações posteriormente, deve começar da versão 0 em sua função migrate.
O HTML renderizado no servidor usa o estado padrão. Se o estado persistido for diferente (por exemplo, tema escuro), haverá um flash de conteúdo incorreto. Lide com isso usando um portão de hidratação ou detecção de tema baseada em CSS.
Múltiplas abas podem sobrescrever o estado persistido umas das outras. A última aba a escrever vence. Considere o evento storage para sincronização entre abas.

Alternativas

Abordagem	Prós	Contras
localStorage (padrão)	Leitura simples e síncrona	Limite de 5MB, bloqueia a thread principal
sessionStorage	Limpa automaticamente ao fechar a aba	Não compartilhado entre abas
IndexedDB	Grande capacidade, assíncrono	Configuração mais complexa
Armazenamento de Cookie	Disponível no servidor (SSR)	Limite de 4KB, enviado com cada requisição

FAQs

Qual é a configuração mínima necessária para usar o middleware persist?

import { persist } from "zustand/middleware";
 
create<MyState>()(
  persist(storeCreator, { name: "storage-key" })
);

Apenas a opção name (a chave do localStorage) é necessária.

Como funciona a hidratação e por que ela causa um breve flash de estado padrão?

Persist lê do armazenamento de forma assíncrona após a criação do store.
Os componentes inicialmente renderizam com o estado padrão, depois atualizam assim que o estado persistido é carregado.
Use onFinishHydration ou hasHydrated() para controlar a renderização até que a hidratação seja concluída.

O que `partialize` faz e por que usá-lo?

partialize controla quais propriedades do estado são salvas no armazenamento.
Por padrão, todo o estado (incluindo funções) é serializado.
Sempre use-o para excluir ações e valores não serializáveis.

Como lidar com migrações de esquema quando a forma do estado persistido muda?

Defina um número de version na configuração do persist.
Forneça uma função migrate que transforma o estado antigo para a nova forma.
migrate é executada quando a versão armazenada é menor que a versão atual.

Como usar um motor de armazenamento personalizado como IndexedDB?

Implemente a interface StateStorage (getItem, setItem, removeItem).
Envolva-a com createJSONStorage(() => yourStorage).
Isso suporta motores de armazenamento síncronos e assíncronos.

Armadilha: O que acontece se o localStorage exceder seu limite de ~5MB?

A escrita falha silenciosamente. O estado não é persistido.
Monitore o uso do armazenamento para stores grandes ou use IndexedDB para maior capacidade.

Armadilha: Múltiplas abas podem sobrescrever o estado persistido umas das outras?

Sim. A última aba a escrever vence.
Considere ouvir o evento storage para sincronização entre abas.
Não há sincronização integrada entre abas no middleware persist do Zustand.

Como limpar programaticamente os dados persistidos?

useAppStore.persist.clearStorage();
// Ou manualmente:
localStorage.removeItem("app-storage");

Como esperar pela hidratação antes de renderizar em um aplicativo Next.js?

Use useAppStore.persist.onFinishHydration() em um useEffect para definir um sinalizador hydrated.
Verifique useAppStore.persist.hasHydrated() para verificações síncronas.
Renderize um estado de carregamento até que a hidratação seja concluída.

Como tipar a opção `partialize` em TypeScript?

persist<AppState>(storeCreator, {
  name: "store",
  partialize: (state): Pick<AppState, "theme" | "language"> => ({
    theme: state.theme,
    language: state.language,
  }),
});

Que tipo a função `migrate` recebe em TypeScript?

migrate recebe unknown para o estado persistido e um number para a versão.
Você deve fazer o cast com cuidado: const state = persisted as Partial<AppState>.

Qual a diferença entre localStorage e sessionStorage para persist?

localStorage persiste entre sessões e abas do navegador.
sessionStorage é limpo quando a aba é fechada e não é compartilhado entre abas.
Alterne passando createJSONStorage(() => sessionStorage) como a opção storage.

Persist Middleware

Buscar na documentação

Persist Middleware