Registry / observability / sentry-zustand-middleware

sentry-zustand-middleware

library4.3.0jsnpmunverified

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.

observability

npm install sentry-zustand-middleware

github ↗package ↗

INSTALL

IMPORT

SIG · SENTRY-ZUSTAND-MID

sentry-zustand-middleware

observabilityjavascriptv4.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sentryMiddleware

✓ import sentryMiddleware from 'sentry-zustand-middleware';

✗ const sentryMiddleware = require('sentry-zustand-middleware');

The library primarily uses ESM exports, CommonJS `require` syntax is generally incorrect for modern tooling.

SentryZustandMiddlewareOptions

✓ import type { SentryZustandMiddlewareOptions } from 'sentry-zustand-middleware';

Import the TypeScript type for middleware options when defining custom configurations.

create

✓ import create from 'zustand';

✗ import { create } from 'zustand';

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.

This quickstart demonstrates basic integration of `sentry-zustand-middleware` with a Zustand store, logging state changes and actions to Sentry (assuming Sentry is initialized).

import create from 'zustand'; import sentryMiddleware from 'sentry-zustand-middleware'; // Ensure Sentry is initialized elsewhere in your application entry point // For example: // import * as Sentry from '@sentry/browser'; // Sentry.init({ dsn: process.env.SENTRY_DSN ?? '' }); interface BearState { bears: number; increase: (by: number) => void; decrease: (by: number) => void; logSomething: (message: string) => void; } const useStore = create<BearState>()( sentryMiddleware((set) => ({ bears: 0, increase: (by) => { set((state) => ({ bears: state.bears + by }), false, 'increaseBears'); }, decrease: (by) => { set((state) => ({ bears: state.bears - by }), false, 'decreaseBears'); }, logSomething: (message) => { // This action will also be logged by the middleware console.log(message); } })), ); // Example usage (ensure Sentry is initialized for actual logging) const store = useStore.getState(); store.increase(5); store.decrease(2); console.log('Current bears:', useStore.getState().bears);

Debug

Known issues

breakingThis 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.

fix

Upgrade `@sentry/browser` and `zustand` to their respective required versions as specified in the `peerDependencies`.

affects: <4.0.0

gotchaSentry 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.

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.

affects: >=1.0.0

gotchaBy 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.

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.

affects: >=1.0.0

gotchaActions 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.

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')`).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Sentry is not initialized

The Sentry SDK's `init` function was not called before the `sentry-zustand-middleware` attempted to send an event.

fix

Call `Sentry.init({ dsn: 'YOUR_DSN' })` at the very beginning of your application's lifecycle, typically in `main.ts` or `App.tsx`.

Error: Middleware cannot be found for 'zustand'

Likely due to mismatched Zustand versions or incorrect import paths for the middleware, especially when mixing CJS and ESM environments.

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.

Property 'bears' does not exist on type 'BearState'

This is a TypeScript error indicating a mismatch between the state interface defined for `create` and the actual state object being used or returned.

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.

Upgrade

Version history

4.3.0latest on npm

Audit

Dependencies

@sentry/browserrequiredRequired for Sentry integration and error reporting functionality.

zustandrequiredThe core state management library this middleware extends.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Thanaen/sentry-zustand-middleware ↗

packagehttps://www.npmjs.com/package/sentry-zustand-middleware ↗