Sentry Zustand Middleware

Common errors

• TypeError: Sentry is not initialized

  cause 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'

  cause 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'

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

Warnings

• breaking 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.
  Fix: Upgrade `@sentry/browser` and `zustand` to their respective required versions as specified in the `peerDependencies`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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')`).

Install

• npm install sentry-zustand-middleware npm
• yarn add sentry-zustand-middleware yarn
• pnpm add sentry-zustand-middleware pnpm

Imports

• sentryMiddleware
  wrong:

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

  correct:

  import sentryMiddleware from '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
  wrong:

  import { create } from 'zustand';

  correct:

  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.

Quickstart

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);