Zustand TypeScript Regression: Middleware Types Broken in v5.0.9

[parvez]

Bug Description

TypeScript middleware types are broken in Zustand v5.0.9. The same code that compiles correctly with Zustand v5.0.3 fails with complex type errors in v5.0.9.

Environment

• Zustand version with bug: 5.0.9
• Zustand version that works: 5.0.3
• TypeScript versions tested: 5.8.2, 5.9.3 (both fail with 5.0.9)
• Build tools tested: Rollup with @rollup/plugin-typescript
• React: 18.3.1

Reproduction

🔗 TypeScript Playground: Live Reproduction

Reproduction code (all 3 middleware patterns tested):

import { create } from 'zustand';
import { devtools, subscribeWithSelector } from 'zustand/middleware';

interface Store {
  count: number;
  increment: () => void;
}

// ❌ TEST 1: devtools only - FAILS in v5.0.9
const useStoreDevtools = create<Store>()(
  devtools(
    (set, get) => ({
      count: 0,
      increment: () => set({ count: get().count + 1 }),
    }),
    { name: 'DevtoolsStore' },
  ),
);

// ❌ TEST 2: subscribeWithSelector only - FAILS in v5.0.9
const useStoreSubscribe = create<Store>()(
  subscribeWithSelector((set, get) => ({
    count: 0,
    increment: () => set({ count: get().count + 1 }),
  })),
);

// ❌ TEST 3: Combined middleware - FAILS in v5.0.9
const useStoreCombined = create<Store>()(
  devtools(
    subscribeWithSelector((set, get) => ({
      count: 0,
      increment: () => set({ count: get().count + 1 }),
    })),
    { name: 'CombinedStore' },
  ),
);

// All 3 tests pass in v5.0.3, all 3 fail in v5.0.9
export { useStoreCombined, useStoreDevtools, useStoreSubscribe };

Steps to reproduce:

1. Create a new project with TypeScript
2. Install [email protected]
3. Create a store with any middleware (code above)
4. Run tsc --noEmit or build with Rollup TypeScript plugin

Verified locally: ✅ Error confirmed on [email protected], works on [email protected]

Error Message

TS2345: Argument of type 'StateCreator<Store, [], [["zustand/devtools", never]]>'
is not assignable to parameter of type 'StateCreator<Store, [], [never, unknown][]>'.

  Type 'StateCreator<Store, [], [["zustand/devtools", never]]>' is not assignable
  to type '{ $$storeMutators?: [never, unknown][] | undefined; }'.

    Types of property '$$storeMutators' are incompatible.
      Type '[["zustand/devtools", never]] | undefined' is not assignable to type '[never, unknown][] | undefined'.
        Type '[["zustand/devtools", never]]' is not assignable to type '[never, unknown][]'.
          Type '["zustand/devtools", never]' is not assignable to type '[never, unknown]'.
            Type at position 0 in source is not compatible with type at position 0 in target.
              Type '"zustand/devtools"' is not assignable to type 'never'.

Additional cascading errors:

TS2349: This expression is not callable.
  Type 'never' has no call signatures.

(For set and get function calls inside the store)

Expected Behavior

The code should compile without errors, as it does in v5.0.3.

Actual Behavior

TypeScript errors are thrown when using any middleware (devtools, subscribeWithSelector, or combinations).

Workarounds

Workaround 1: Downgrade to v5.0.3

npm install [email protected]

Workaround 2: Type assertion (not recommended)

const useStore = (create as any)(
  (devtools as any)(
    (set, get) => ({...}),
    { name: 'Store' },
  ),
) as UseBoundStore<StoreApi<Store>>;

Version Comparison (Verified Locally)

Version	devtools	subscribeWithSelector	Combined	Build Status
5.0.3	✅ Works	✅ Works	✅ Works	✅ Clean build
5.0.9	❌ TS2345	❌ TS2345	❌ TS2345	❌ Build fails

Test command used:

# Install v5.0.9 and test
pnpm add [email protected]
npx tsc --noEmit  # ❌ 6 errors

# Downgrade to v5.0.3 and test
pnpm add [email protected]
npx tsc --noEmit  # ✅ 0 errors

Analysis

The regression appears to be in the $$storeMutators type definition. Between v5.0.3 and v5.0.9, the middleware type inference changed in a way that breaks the constraint [never, unknown][].

Diff of middleware/devtools.d.ts (5.0.3 vs 5.0.9):

The type parameter naming changed slightly:

• v5.0.3: [...a0: Cast<T, unknown[]>, a1: undefined]
• v5.0.9: [...args0: Cast<T, unknown[]>, arg1: undefined]

While this naming change seems innocuous, there may be other changes in the core type definitions affecting the StoreMutatorIdentifier resolution.

Likely Cause: PR #3308

Based on the closed PRs, the v5.0.9 release includes:

PR	Title	Merged
#3308	experimental: unstable ssrSafe middleware	Nov 29, 2025

This PR added the new ssrSafe middleware and is the only code change in v5.0.9. The addition of a new middleware likely modified the core type definitions (StoreMutators, StoreMutatorIdentifier) and inadvertently tightened the $$storeMutators constraint.

Suggested Fix

Review changes in PR #3308, specifically:

• src/vanilla.d.ts (StoreMutators, StoreMutatorIdentifier)
• src/middleware/devtools.d.ts
• src/middleware/subscribeWithSelector.d.ts
• Any new type declarations for ssrSafe

The $$storeMutators type constraint appears to be too strict in v5.0.9.

---

Additional Context

This was discovered while migrating a production application. The same codebase works with v5.0.3 (installed via ^5.0.0-rc.2 resolution) but fails when explicitly using v5.0.9.

Projects affected:

• Any project using Zustand middleware with TypeScript
• Both single middleware and combined middleware patterns

Reproduction Link

https://www.typescriptlang.org/play/?#code/PQKhCgAIUgtBXAzgFwIYDsAmkBuBWAOgAYCBOSAFQE8AHAUwGUBjAJwEsblIBZNzTADZ0A7qhZ1IAIXgBzSAFpIANTrsAZmzrYASnRosA9pnhNkbA+igRokQKDkkAMIB5AHIAxAJLbuAUQAiAFyUABZsiJCqhiyQYZDi+kYmbABGQpDCbMjBkABeSGhYAAKEJKRWdo6unt7+QQDqBiwA1uFMjeKmAlTpmdl5KBiYxcQEAMxW5RQGcXqGxkx0AeUAjASQ6DQAtjHoAwICufmDw6XlAExrGwAekMiITAry6AY+m5m3oYjyGkIEdxM2HwsKJBCgMM6jAAseAUkAAJHCUI06Nx4GhkI1wshaBI3ohNqhkExguUAETUeiQADkpP6BUwwEwdBwGIMAkQpKpMXCzy4qEQiDYMnQqFSEgxtxx1PQzNUNKswHAbE2NEaXAA3pBWHRCRIAL6QNSGbZUumDKkAbiVKrVkE1TJZBjZiAANJBEPBkvd2Mk6HVegw6EJTI1IAajQYTWasMA3vwhKJxJbwEr0MhVGpUAtIAwMeI7VAtQZ4Gmguh4JtfSwrZAdtrNnRS5AABQASkgAF4AHy4Ax8K16lPAYCQQAy5JQfAwKJBlkEHaz2ZALF1YW4AIIeAAyDB2uBKZHAbV2XCQjDzdD8zIX4Q7WvEuoAPLnkV2283C-Onez37Xa83EHQyBujIgHtt2LbqoWv5FiWyBBEQLpQb+bDoPWjZwS2YE9gByDNpqbSwUEIG4a2BAEWmkAANQzmGraIdBep0Uhmoig2QRUpejrOs+SZhvRkBMa2VrgMOY4TlOkBnEEHpeqwKR+gGQZ0CG0TLt0ijrluO4oXuIxlEeKCQKePGMJ63ryZ2d46umT7nq+rY-u6Zlyb6-pZIGwZ5s2-6AcBoGdj2eFIeRGEIUhKFoU2bYBe6gF4TBTbEW2ZHFhR1HLLR-GMYJwmieOFCTtOoxBA4kbJChWiQHGggiGIEgaRu267vgemHhYhnGeepWVhV2C3tqj4mfZjmfs6jm1jJ5muYpnmNN5OF+cgWEQUhtYhfB-HQRF4gNlFy04fF62QElpEhVRNGMZttFMdBLGoGx1LdeVMqYCZXJ6vxOVDiOa77JAoy3HQKDhDQ-LhDpLUkKMbqoH9AOZmwBwQ-uZR0FcqosBqRkASZT29W6nXIpx14Ezj54MM5Pr6laQA

[dbritto-dev]

@parvez would you mind creating stackblitz demo?

[parvez]

seems like rollup is causing issue for me. investigating further. suggests the issue is with how Rollup's plugin resolves/processes the middleware types differently than tsc directly.

Tool	Version	Zustand 5.0.9
@rollup/plugin-typescript	11.1.6	❌ TS2345
@rollup/plugin-typescript	12.3.0	❌ TS2345
Standalone tsc	5.9.3	✅ Works

[parvez]

NOT A BUG!

The error was caused by stale node_modules!

After a fresh pnpm install, the build passes with direct zustand imports

✅ No TypeScript errors

This was likely caused by:

• Stale cached type definitions from an older Zustand version
• pnpm's symlink structure getting out of sync

Lesson learned: When encountering bizarre TypeScript errors, try rm -rf node_modules pnpm-lock.yaml && pnpm install first!