{"id":17471,"library":"sentry-zustand-middleware","title":"Sentry Zustand Middleware","description":"sentry-zustand-middleware is a specialized middleware for Zustand stores designed to automatically log state changes and actions to Sentry. This package is currently at version 4.3.0 and typically follows the release cycles of its peer dependencies, Zustand and Sentry, to ensure compatibility. Its core function is to capture the state snapshots and the actions that modify them, providing enhanced debugging capabilities and visibility into application state flow during error reporting. A key differentiator is its optional `stateTransformer` function, which allows developers to clean, filter, or obfuscate sensitive data from the Zustand state before it is sent to Sentry, preventing oversharing of private information. It provides a direct integration without manual Sentry calls within every action or state update.","status":"active","version":"4.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/Thanaen/sentry-zustand-middleware","tags":["javascript","middleware","sentry","zustand","typescript"],"install":[{"cmd":"npm install sentry-zustand-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add sentry-zustand-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add sentry-zustand-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Sentry integration and error reporting functionality.","package":"@sentry/browser","optional":false},{"reason":"The core state management library this middleware extends.","package":"zustand","optional":false}],"imports":[{"note":"The library primarily uses ESM exports, CommonJS `require` syntax is generally incorrect for modern tooling.","wrong":"const sentryMiddleware = require('sentry-zustand-middleware');","symbol":"sentryMiddleware","correct":"import sentryMiddleware from 'sentry-zustand-middleware';"},{"note":"Import the TypeScript type for middleware options when defining custom configurations.","symbol":"SentryZustandMiddlewareOptions","correct":"import type { SentryZustandMiddlewareOptions } from 'sentry-zustand-middleware';"},{"note":"While `create` is often imported as a named export in older Zustand versions, the modern pattern is a default import for `zustand/vanilla` or `zustand` itself.","wrong":"import { create } from 'zustand';","symbol":"create","correct":"import create from 'zustand';"}],"quickstart":{"code":"import create from 'zustand';\nimport sentryMiddleware from 'sentry-zustand-middleware';\n\n// Ensure Sentry is initialized elsewhere in your application entry point\n// For example:\n// import * as Sentry from '@sentry/browser';\n// Sentry.init({ dsn: process.env.SENTRY_DSN ?? '' });\n\ninterface BearState {\n  bears: number;\n  increase: (by: number) => void;\n  decrease: (by: number) => void;\n  logSomething: (message: string) => void;\n}\n\nconst useStore = create<BearState>()(\n  sentryMiddleware((set) => ({\n    bears: 0,\n    increase: (by) => {\n      set((state) => ({ bears: state.bears + by }), false, 'increaseBears');\n    },\n    decrease: (by) => {\n      set((state) => ({ bears: state.bears - by }), false, 'decreaseBears');\n    },\n    logSomething: (message) => {\n      // This action will also be logged by the middleware\n      console.log(message);\n    }\n  })),\n);\n\n// Example usage (ensure Sentry is initialized for actual logging)\nconst store = useStore.getState();\nstore.increase(5);\nstore.decrease(2);\n\nconsole.log('Current bears:', useStore.getState().bears);\n","lang":"typescript","description":"This quickstart demonstrates basic integration of `sentry-zustand-middleware` with a Zustand store, logging state changes and actions to Sentry (assuming Sentry is initialized)."},"warnings":[{"fix":"Upgrade `@sentry/browser` and `zustand` to their respective required versions as specified in the `peerDependencies`.","message":"This middleware requires specific peer dependency versions for Sentry and Zustand. Ensure your project's `@sentry/browser` is `>= 7.87.0` and `zustand` is `>= 4.1.3` to avoid compatibility issues.","severity":"breaking","affected_versions":"<4.0.0"},{"fix":"Ensure `Sentry.init()` is called and configured correctly at your application's entry point, prior to any Zustand store creation that uses this middleware.","message":"Sentry must be initialized BEFORE the `sentry-zustand-middleware` is used. If Sentry is not initialized, the middleware will not send events, and you may not see errors, potentially leading to silent failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement a `stateTransformer` function in the middleware options to filter, sanitize, or redact sensitive parts of your state before it is sent to Sentry. For example, remove `password` fields or large arrays.","message":"By default, the middleware logs the entire Zustand state. If your state contains sensitive user information, tokens, or large objects, this data will be sent to Sentry. This can lead to privacy breaches or excessive Sentry usage.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always provide a descriptive string as the third argument to Zustand's `set` function within your store actions (e.g., `set((state) => ({ count: state.count + 1 }), false, 'incrementCount')`).","message":"Actions are logged with the name provided as the third argument to the `set` function (e.g., `set(..., false, 'actionName')`). If no action name is provided, Sentry might log a generic 'Anonymous' action, making debugging harder.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Call `Sentry.init({ dsn: 'YOUR_DSN' })` at the very beginning of your application's lifecycle, typically in `main.ts` or `App.tsx`.","cause":"The Sentry SDK's `init` function was not called before the `sentry-zustand-middleware` attempted to send an event.","error":"TypeError: Sentry is not initialized"},{"fix":"Verify that your `zustand` and `sentry-zustand-middleware` packages are compatible and that you are using the correct import syntax (ESM `import` statements) throughout your project.","cause":"Likely due to mismatched Zustand versions or incorrect import paths for the middleware, especially when mixing CJS and ESM environments.","error":"Error: Middleware cannot be found for 'zustand'"},{"fix":"Review your `BearState` interface and ensure all properties and methods are correctly defined and that the initial state and `set` calls conform to this interface.","cause":"This is a TypeScript error indicating a mismatch between the state interface defined for `create` and the actual state object being used or returned.","error":"Property 'bears' does not exist on type 'BearState'"}],"ecosystem":"npm","meta_description":null}