Por que a invocação dupla create()() é necessária com middleware?

O primeiro () ajuda o TypeScript a inferir corretamente os tipos combinados de middleware. Sem ele, o TypeScript não consegue propagar informações de tipo através da cadeia de middleware.

Middleware do Zustand

Q: Quais middlewares integrados o Zustand fornece?

persist -- salva e restaura o estado no armazenamento (localStorage por padrão). devtools -- conecta-se à extensão do navegador Redux DevTools. immer -- permite atualizações de estado em estilo mutável que produzem estado imutável. subscribeWithSelector -- permite assinar fatias de estado específicas fora do React.

Q: Qual é a ordem recomendada para empilhar middlewares?

devtools mais externo, depois subscribeWithSelector, depois persist, e immer o mais interno. Middleware é aplicado de dentro para fora: o mais interno é executado primeiro.

Q: Como subscribeWithSelector difere do .subscribe() padrão?

Ele estende .subscribe() para aceitar um seletor e uma função de igualdade. Você pode assinar um campo específico e disparar o callback apenas quando esse campo mudar.

Q: Armadilha: O persist serializa funções no estado?

Sim, JSON.stringify serializa funções como null. Use partialize para excluir ações e valores não serializáveis. Funções perdidas durante a serialização são restauradas dos padrões na reidratação.

Q: O subscribeWithSelector deve envolver persist ou vice-versa?

subscribeWithSelector deve envolver persist (não o contrário) se você quiser assinar alterações de estado persistido.

Receita

O Zustand oferece vários middlewares integrados: persist para armazenamento, devtools para Redux DevTools, immer para atualizações imutáveis e subscribeWithSelector para assinaturas granulares. Empilhe-os aninhando.

import { create } from "zustand";
import { devtools, persist } from "zustand/middleware";
import { immer } from "zustand/middleware/immer";
 
interface AppState {
  count: number;
  increment: () => void;
}
 
export const useStore = create<AppState>()(
  devtools(
    persist(
      immer((set) => ({
        count: 0,
        increment: () =>
          set((state) => {
            state.count += 1; // Mutação direta graças ao immer
          }),
      })),
      { name: "app-store" }
    ),
    { name: "AppStore" }
  )
);

Exemplo de Trabalho

// stores/settings-store.ts
import { create } from "zustand";
import { devtools, persist, subscribeWithSelector } from "zustand/middleware";
import { immer } from "zustand/middleware/immer";
 
interface Settings {
  theme: "light" | "dark" | "system";
  fontSize: number;
  language: string;
  notifications: {
    email: boolean;
    push: boolean;
    sms: boolean;
  };
}
 
interface SettingsStore extends Settings {
  setTheme: (theme: Settings["theme"]) => void;
  setFontSize: (size: number) => void;
  setLanguage: (lang: string) => void;
  toggleNotification: (channel: keyof Settings["notifications"]) => void;
  resetToDefaults: () => void;
}
 
const defaults: Settings = {
  theme: "system",
  fontSize: 16,
  language: "en",
  notifications: { email: true, push: true, sms: false },
};
 
export const useSettingsStore = create<SettingsStore>()(
  devtools(
    subscribeWithSelector(
      persist(
        immer((set) => ({
          ...defaults,
 
          setTheme: (theme) =>
            set((state) => {
              state.theme = theme;
            }),
 
          setFontSize: (size) =>
            set((state) => {
              state.fontSize = Math.max(12, Math.min(24, size));
            }),
 
          setLanguage: (lang) =>
            set((state) => {
              state.language = lang;
            }),
 
          toggleNotification: (channel) =>
            set((state) => {
              state.notifications[channel] = !state.notifications[channel];
            }),
 
          resetToDefaults: () =>
            set((state) => {
              Object.assign(state, defaults);
            }),
        })),
        {
          name: "settings-storage",
          partialize: (state) => ({
            theme: state.theme,
            fontSize: state.fontSize,
            language: state.language,
            notifications: state.notifications,
          }),
        }
      )
    ),
    { name: "SettingsStore" }
  )
);
 
// Assina alterações de estado específicas
useSettingsStore.subscribe(
  (state) => state.theme,
  (theme) => {
    document.documentElement.setAttribute("data-theme", theme);
  }
);
 
useSettingsStore.subscribe(
  (state) => state.fontSize,
  (fontSize) => {
    document.documentElement.style.fontSize = `${fontSize}px`;
  }
);

// components/settings-panel.tsx
"use client";
 
import { useSettingsStore } from "@/stores/settings-store";
 
export function SettingsPanel() {
  const theme = useSettingsStore((s) => s.theme);
  const fontSize = useSettingsStore((s) => s.fontSize);
  const notifications = useSettingsStore((s) => s.notifications);
  const setTheme = useSettingsStore((s) => s.setTheme);
  const setFontSize = useSettingsStore((s) => s.setFontSize);
  const toggleNotification = useSettingsStore((s) => s.toggleNotification);
  const resetToDefaults = useSettingsStore((s) => s.resetToDefaults);
 
  return (
    <div>
      <section>
        <h3>Tema</h3>
        <select value={theme} onChange={(e) => setTheme(e.target.value as any)}>
          <option value="light">Claro</option>
          <option value="dark">Escuro</option>
          <option value="system">Sistema</option>
        </select>
      </section>
 
      <section>
        <h3>Tamanho da Fonte: {fontSize}px</h3>
        <input
          type="range"
          min={12}
          max={24}
          value={fontSize}
          onChange={(e) => setFontSize(Number(e.target.value))}
        />
      </section>
 
      <section>
        <h3>Notificações</h3>
        {(Object.keys(notifications) as Array<keyof typeof notifications>).map((ch) => (
          <label key={ch}>
            <input
              type="checkbox"
              checked={notifications[ch]}
              onChange={() => toggleNotification(ch)}
            />
            {ch}
          </label>
        ))}
      </section>
 
      <button onClick={resetToDefaults}>Redefinir para padrões</button>
    </div>
  );
}

Análise Profunda

Como Funciona

Middleware envolve a função criadora da store, adicionando comportamento antes ou depois das alterações de estado.
persist: Serializa o estado para armazenamento (localStorage por padrão) e o restaura na montagem.
devtools: Conecta-se à extensão do navegador Redux DevTools para depuração de viagem no tempo.
immer: Envolve set para que você possa escrever atualizações em estilo mutável que produzem estado imutável.
subscribeWithSelector: Estende .subscribe() para aceitar um seletor e uma função de igualdade, permitindo efeitos colaterais granulares.
Middleware é aplicado de dentro para fora. O middleware mais interno é executado primeiro.

Variações

Ordem de middleware (recomendada):

// devtools mais externo, depois subscribeWithSelector, depois persist, depois immer o mais interno
create<Store>()(
  devtools(
    subscribeWithSelector(
      persist(
        immer((set) => ({ ... })),
        { name: "store" }
      )
    )
  )
);

Middleware personalizado:

import { StateCreator, StoreMutatorIdentifier } from "zustand";
 
type Logger = <
  T,
  Mps extends [StoreMutatorIdentifier, unknown][] = [],
  Mcs extends [StoreMutatorIdentifier, unknown][] = []
>(
  f: StateCreator<T, Mps, Mcs>,
  name?: string
) => StateCreator<T, Mps, Mcs>;
 
const logger: Logger = (f, name) => (set, get, store) => {
  const loggedSet: typeof set = (...args) => {
    set(...(args as any));
    console.log(`[${name || "store"}]`, get());
  };
  return f(loggedSet, get, store);
};
 
// Uso
const useStore = create(logger((set) => ({ count: 0 }), "CountStore"));

Notas de TypeScript

Ao empilhar middlewares, use create<State>()() (invocação dupla) para ajudar o TypeScript a inferir os tipos combinados.
Cada middleware adiciona seus próprios mutadores de tipo. A ordem afeta a inferência de tipo.
partialize no middleware persist deve retornar um subconjunto do estado com segurança de tipo.

// O padrão ()() é necessário para a inferência de tipo de middleware
export const useStore = create<State>()(
  devtools(persist(immer((set) => ({ ... })), { name: "store" }))
);

Armadilhas

A ordem do middleware importa tanto para o comportamento quanto para o TypeScript. Sempre coloque devtools mais externo e immer o mais interno.
Usar immer sem a importação de middleware de zustand/middleware/immer não funcionará. É um pacote separado.
persist serializa o estado com JSON.stringify por padrão. Funções, Datas, Maps e Sets serão perdidos. Use partialize para excluir valores não serializáveis.
devtools adiciona sobrecarga. Desabilite-o em produção: devtools(fn, { enabled: process.env.NODE_ENV === "development" }).
subscribeWithSelector deve envolver persist (não o contrário) se você quiser assinar alterações de estado persistido.
Empilhar muitos middlewares torna a depuração mais difícil. Adicione apenas os middlewares que você realmente precisa.

Alternativas

Abordagem	Prós	Contras
Middleware Zustand integrado	Suporte oficial, bem tipado	Conjunto fixo de middlewares
Middleware personalizado	Adaptado às suas necessidades	Deve lidar com tipos manualmente
Sem middleware (store simples)	Mais simples, mais rápido	Sem persistência, devtools ou immer
Middleware Redux Toolkit	Ecossistema maduro	Biblioteca diferente, mais boilerplate

FAQs

Quais middlewares integrados o Zustand fornece?

persist -- salva e restaura o estado no armazenamento (localStorage por padrão).
devtools -- conecta-se à extensão do navegador Redux DevTools.
immer -- permite atualizações de estado em estilo mutável que produzem estado imutável.
subscribeWithSelector -- permite assinar fatias de estado específicas fora do React.

Qual é a ordem recomendada para empilhar middlewares?

devtools mais externo, depois subscribeWithSelector, depois persist, e immer o mais interno.
Middleware é aplicado de dentro para fora: o mais interno é executado primeiro.

Por que a invocação dupla `create<State>()()` é necessária com middleware?

O primeiro () ajuda o TypeScript a inferir corretamente os tipos combinados de middleware.
Sem ele, o TypeScript não consegue propagar informações de tipo através da cadeia de middleware.

Como `subscribeWithSelector` difere do `.subscribe()` padrão?

Ele estende .subscribe() para aceitar um seletor e uma função de igualdade.
Você pode assinar um campo específico e disparar o callback apenas quando esse campo mudar.

useStore.subscribe(
  (state) => state.theme,
  (theme) => document.documentElement.setAttribute("data-theme", theme)
);

Como escrever middleware personalizado?

Middleware personalizado envolve a função criadora da store e intercepta set, get ou store.
Retorna um novo criador de store que adiciona comportamento antes ou depois das alterações de estado.

Armadilha: O que acontece se você colocar `immer` fora de `persist` em vez de dentro?

Immer deve ser o middleware mais interno. Colocá-lo fora de persist ou devtools não funcionará corretamente.
O proxy de rascunho mutável não funcionará como esperado se outro middleware o envolver.

Armadilha: O `persist` serializa funções no estado?

Sim, JSON.stringify serializa funções como null.
Use partialize para excluir ações e valores não serializáveis.
Funções perdidas durante a serialização são restauradas dos padrões na reidratação.

Como desabilitar o middleware devtools em produção?

devtools(storeCreator, {
  name: "AppStore",
  enabled: process.env.NODE_ENV === "development",
});

O `subscribeWithSelector` deve envolver `persist` ou vice-versa?

subscribeWithSelector deve envolver persist (não o contrário) se você quiser assinar alterações de estado persistido.

Como cada middleware afeta os tipos TypeScript?

Cada middleware adiciona seus próprios mutadores de tipo à cadeia de tipos da store.
A ordem do middleware afeta a inferência de tipo, que é por que a ordem consistente importa.
Use create<State>()() para deixar o TypeScript inferir os tipos combinados corretamente.

Como funciona `partialize` no middleware persist?

persist(storeCreator, {
  name: "settings-storage",
  partialize: (state) => ({
    theme: state.theme,
    fontSize: state.fontSize,
  }),
});

Apenas as propriedades retornadas são salvas no armazenamento. Todo o resto é excluído.

Links Relacionados

Receita

import { create } from "zustand";
import { devtools, persist } from "zustand/middleware";
import { immer } from "zustand/middleware/immer";
 
interface AppState {
  count: number;
  increment: () => void;
}
 
export const useStore = create<AppState>()(
  devtools(
    persist(
      immer((set) => ({
        count: 0,
        increment: () =>
          set((state) => {
            state.count += 1; // Mutação direta graças ao immer
          }),
      })),
      { name: "app-store" }
    ),
    { name: "AppStore" }
  )
);

Exemplo de Trabalho

// stores/settings-store.ts
import { create } from "zustand";
import { devtools, persist, subscribeWithSelector } from "zustand/middleware";
import { immer } from "zustand/middleware/immer";
 
interface Settings {
  theme: "light" | "dark" | "system";
  fontSize: number;
  language: string;
  notifications: {
    email: boolean;
    push: boolean;
    sms: boolean;
  };
}
 
interface SettingsStore extends Settings {
  setTheme: (theme: Settings["theme"]) => void;
  setFontSize: (size: number) => void;
  setLanguage: (lang: string) => void;
  toggleNotification: (channel: keyof Settings["notifications"]) => void;
  resetToDefaults: () => void;
}
 
const defaults: Settings = {
  theme: "system",
  fontSize: 16,
  language: "en",
  notifications: { email: true, push: true, sms: false },
};
 
export const useSettingsStore = create<SettingsStore>()(
  devtools(
    subscribeWithSelector(
      persist(
        immer((set) => ({
          ...defaults,
 
          setTheme: (theme) =>
            set((state) => {
              state.theme = theme;
            }),
 
          setFontSize: (size) =>
            set((state) => {
              state.fontSize = Math.max(12, Math.min(24, size));
            }),
 
          setLanguage: (lang) =>
            set((state) => {
              state.language = lang;
            }),
 
          toggleNotification: (channel) =>
            set((state) => {
              state.notifications[channel] = !state.notifications[channel];
            }),
 
          resetToDefaults: () =>
            set((state) => {
              Object.assign(state, defaults);
            }),
        })),
        {
          name: "settings-storage",
          partialize: (state) => ({
            theme: state.theme,
            fontSize: state.fontSize,
            language: state.language,
            notifications: state.notifications,
          }),
        }
      )
    ),
    { name: "SettingsStore" }
  )
);
 
// Assina alterações de estado específicas
useSettingsStore.subscribe(
  (state) => state.theme,
  (theme) => {
    document.documentElement.setAttribute("data-theme", theme);
  }
);
 
useSettingsStore.subscribe(
  (state) => state.fontSize,
  (fontSize) => {
    document.documentElement.style.fontSize = `${fontSize}px`;
  }
);

// components/settings-panel.tsx
"use client";
 
import { useSettingsStore } from "@/stores/settings-store";
 
export function SettingsPanel() {
  const theme = useSettingsStore((s) => s.theme);
  const fontSize = useSettingsStore((s) => s.fontSize);
  const notifications = useSettingsStore((s) => s.notifications);
  const setTheme = useSettingsStore((s) => s.setTheme);
  const setFontSize = useSettingsStore((s) => s.setFontSize);
  const toggleNotification = useSettingsStore((s) => s.toggleNotification);
  const resetToDefaults = useSettingsStore((s) => s.resetToDefaults);
 
  return (
    <div>
      <section>
        <h3>Tema</h3>
        <select value={theme} onChange={(e) => setTheme(e.target.value as any)}>
          <option value="light">Claro</option>
          <option value="dark">Escuro</option>
          <option value="system">Sistema</option>
        </select>
      </section>
 
      <section>
        <h3>Tamanho da Fonte: {fontSize}px</h3>
        <input
          type="range"
          min={12}
          max={24}
          value={fontSize}
          onChange={(e) => setFontSize(Number(e.target.value))}
        />
      </section>
 
      <section>
        <h3>Notificações</h3>
        {(Object.keys(notifications) as Array<keyof typeof notifications>).map((ch) => (
          <label key={ch}>
            <input
              type="checkbox"
              checked={notifications[ch]}
              onChange={() => toggleNotification(ch)}
            />
            {ch}
          </label>
        ))}
      </section>
 
      <button onClick={resetToDefaults}>Redefinir para padrões</button>
    </div>
  );
}

Análise Profunda

Como Funciona

Middleware envolve a função criadora da store, adicionando comportamento antes ou depois das alterações de estado.
persist: Serializa o estado para armazenamento (localStorage por padrão) e o restaura na montagem.
devtools: Conecta-se à extensão do navegador Redux DevTools para depuração de viagem no tempo.
immer: Envolve set para que você possa escrever atualizações em estilo mutável que produzem estado imutável.
subscribeWithSelector: Estende .subscribe() para aceitar um seletor e uma função de igualdade, permitindo efeitos colaterais granulares.
Middleware é aplicado de dentro para fora. O middleware mais interno é executado primeiro.

Variações

Ordem de middleware (recomendada):

// devtools mais externo, depois subscribeWithSelector, depois persist, depois immer o mais interno
create<Store>()(
  devtools(
    subscribeWithSelector(
      persist(
        immer((set) => ({ ... })),
        { name: "store" }
      )
    )
  )
);

Middleware personalizado:

import { StateCreator, StoreMutatorIdentifier } from "zustand";
 
type Logger = <
  T,
  Mps extends [StoreMutatorIdentifier, unknown][] = [],
  Mcs extends [StoreMutatorIdentifier, unknown][] = []
>(
  f: StateCreator<T, Mps, Mcs>,
  name?: string
) => StateCreator<T, Mps, Mcs>;
 
const logger: Logger = (f, name) => (set, get, store) => {
  const loggedSet: typeof set = (...args) => {
    set(...(args as any));
    console.log(`[${name || "store"}]`, get());
  };
  return f(loggedSet, get, store);
};
 
// Uso
const useStore = create(logger((set) => ({ count: 0 }), "CountStore"));

Notas de TypeScript

Ao empilhar middlewares, use create<State>()() (invocação dupla) para ajudar o TypeScript a inferir os tipos combinados.
Cada middleware adiciona seus próprios mutadores de tipo. A ordem afeta a inferência de tipo.
partialize no middleware persist deve retornar um subconjunto do estado com segurança de tipo.

// O padrão ()() é necessário para a inferência de tipo de middleware
export const useStore = create<State>()(
  devtools(persist(immer((set) => ({ ... })), { name: "store" }))
);

Armadilhas

A ordem do middleware importa tanto para o comportamento quanto para o TypeScript. Sempre coloque devtools mais externo e immer o mais interno.
Usar immer sem a importação de middleware de zustand/middleware/immer não funcionará. É um pacote separado.
persist serializa o estado com JSON.stringify por padrão. Funções, Datas, Maps e Sets serão perdidos. Use partialize para excluir valores não serializáveis.
devtools adiciona sobrecarga. Desabilite-o em produção: devtools(fn, { enabled: process.env.NODE_ENV === "development" }).
subscribeWithSelector deve envolver persist (não o contrário) se você quiser assinar alterações de estado persistido.
Empilhar muitos middlewares torna a depuração mais difícil. Adicione apenas os middlewares que você realmente precisa.

Alternativas

Abordagem	Prós	Contras
Middleware Zustand integrado	Suporte oficial, bem tipado	Conjunto fixo de middlewares
Middleware personalizado	Adaptado às suas necessidades	Deve lidar com tipos manualmente
Sem middleware (store simples)	Mais simples, mais rápido	Sem persistência, devtools ou immer
Middleware Redux Toolkit	Ecossistema maduro	Biblioteca diferente, mais boilerplate

FAQs

Quais middlewares integrados o Zustand fornece?

persist -- salva e restaura o estado no armazenamento (localStorage por padrão).
devtools -- conecta-se à extensão do navegador Redux DevTools.
immer -- permite atualizações de estado em estilo mutável que produzem estado imutável.
subscribeWithSelector -- permite assinar fatias de estado específicas fora do React.

Qual é a ordem recomendada para empilhar middlewares?

devtools mais externo, depois subscribeWithSelector, depois persist, e immer o mais interno.
Middleware é aplicado de dentro para fora: o mais interno é executado primeiro.

Por que a invocação dupla `create<State>()()` é necessária com middleware?

O primeiro () ajuda o TypeScript a inferir corretamente os tipos combinados de middleware.
Sem ele, o TypeScript não consegue propagar informações de tipo através da cadeia de middleware.

Como `subscribeWithSelector` difere do `.subscribe()` padrão?

Ele estende .subscribe() para aceitar um seletor e uma função de igualdade.
Você pode assinar um campo específico e disparar o callback apenas quando esse campo mudar.

useStore.subscribe(
  (state) => state.theme,
  (theme) => document.documentElement.setAttribute("data-theme", theme)
);

Como escrever middleware personalizado?

Middleware personalizado envolve a função criadora da store e intercepta set, get ou store.
Retorna um novo criador de store que adiciona comportamento antes ou depois das alterações de estado.

Armadilha: O que acontece se você colocar `immer` fora de `persist` em vez de dentro?

Immer deve ser o middleware mais interno. Colocá-lo fora de persist ou devtools não funcionará corretamente.
O proxy de rascunho mutável não funcionará como esperado se outro middleware o envolver.

Armadilha: O `persist` serializa funções no estado?

Sim, JSON.stringify serializa funções como null.
Use partialize para excluir ações e valores não serializáveis.
Funções perdidas durante a serialização são restauradas dos padrões na reidratação.

Como desabilitar o middleware devtools em produção?

devtools(storeCreator, {
  name: "AppStore",
  enabled: process.env.NODE_ENV === "development",
});

O `subscribeWithSelector` deve envolver `persist` ou vice-versa?

subscribeWithSelector deve envolver persist (não o contrário) se você quiser assinar alterações de estado persistido.

Como cada middleware afeta os tipos TypeScript?

Cada middleware adiciona seus próprios mutadores de tipo à cadeia de tipos da store.
A ordem do middleware afeta a inferência de tipo, que é por que a ordem consistente importa.
Use create<State>()() para deixar o TypeScript inferir os tipos combinados corretamente.

Como funciona `partialize` no middleware persist?

persist(storeCreator, {
  name: "settings-storage",
  partialize: (state) => ({
    theme: state.theme,
    fontSize: state.fontSize,
  }),
});

Apenas as propriedades retornadas são salvas no armazenamento. Todo o resto é excluído.

Middleware do Zustand

Buscar na documentação

Middleware do Zustand