veza/apps/web/src/docs/STATE_DEBUGGING.md

State Debugging Guide

FE-STATE-007: Add state debugging tools

This document outlines how to use Redux DevTools for debugging Zustand stores in the Veza frontend application.

Overview

All Zustand stores in the application are configured with Redux DevTools middleware, which allows you to:

• Inspect state changes in real-time
• Time-travel through state history
• Export/import state snapshots
• Monitor action dispatches and their effects

Setup

Redux DevTools is automatically enabled for all stores in development mode. The middleware is configured with:

• Store names for easy identification in DevTools
• Development-only activation (disabled in production)

Stores Available for Debugging

The following stores are configured with DevTools:

1. AuthStore (apps/web/src/features/auth/store/authStore.ts)

   • Manages user authentication state
   • Tracks login/logout actions
   • Monitors user profile updates
   • Note: Contains user field (domain data - will migrate to React Query per Action 4.1.1.x)

2. UIStore (apps/web/src/stores/ui.ts)

   • Manages UI preferences (theme, language, sidebar)
   • Tracks notification state
   • Monitors UI state changes
   • Category: UI State (appropriate for Zustand)

3. LibraryStore (apps/web/src/stores/library.ts)

   • Manages library items and favorites
   • Tracks filter changes
   • Monitors item uploads and deletions
   • Note: Contains domain data (will migrate to React Query per Epic 4.1)

4. ChatStore (apps/web/src/features/chat/store/chatStore.ts) - Action 4.5.1.5: Moved from stores/chat.ts

   • Manages chat conversations and messages
   • Tracks WebSocket connection state
   • Monitors message operations
   • Note: ⚠️ DUPLICATE - Also exists at features/chat/store/chatStore.ts (needs consolidation per Action 4.5.1.5)

5. CartStore (apps/web/src/stores/cartStore.ts)

   • Manages shopping cart items
   • Tracks cart operations (add, remove, update quantity)
   • Category: UI State (client-side cart before checkout)

6. PlayerStore (apps/web/src/features/player/store/playerStore.ts)

   • Manages audio player state (current track, playback state, queue)
   • Tracks player controls and settings
   • Category: UI State (audio player state)

Using Redux DevTools

Installation

1. Install the Redux DevTools Extension for your browser:
   • Chrome/Edge
   • Firefox

Usage

1. Open DevTools: Press F12 or right-click → Inspect
2. Navigate to Redux Tab: Click on the "Redux" tab in DevTools
3. Select Store: Use the dropdown to select which store to inspect (AuthStore, UIStore, LibraryStore, ChatStore, CartStore, PlayerStore)
4. Inspect State: View the current state tree
5. Time Travel: Use the slider or buttons to navigate through state history
6. Action Details: Click on any action to see its payload and resulting state changes

Features

State Inspection

• View the complete state tree
• Search for specific state properties
• Expand/collapse nested objects

Action Monitoring

• See all dispatched actions in chronological order
• View action payloads
• See state diffs for each action

Time Travel Debugging

• Jump to any previous state
• Replay actions from a specific point
• Export state snapshots for sharing

State Export/Import

• Export current state as JSON
• Import state to restore a previous state
• Useful for reproducing bugs

Example Workflow

Debugging a State Issue

1. Reproduce the Issue: Perform the action that causes the problem
2. Inspect Actions: Look at the Redux DevTools action log to see what actions were dispatched
3. Check State Changes: Review the state diff to see what changed
4. Time Travel: Go back to before the issue occurred
5. Export State: Export the problematic state for further analysis

Testing State Changes

1. Record Actions: Perform a series of actions
2. Export State: Export the final state
3. Reset: Clear the store or reload the page
4. Import State: Import the exported state to restore it
5. Verify: Confirm the state is restored correctly

Best Practices

1. Use Descriptive Store Names: Store names in DevTools help identify which store you're debugging
2. Monitor in Development: DevTools is only enabled in development mode for performance
3. Export Problematic States: When reporting bugs, export the state snapshot to help developers reproduce the issue
4. Time Travel Carefully: Be aware that time-traveling can cause side effects (e.g., API calls won't be replayed)

Troubleshooting

DevTools Not Showing Stores

• Ensure you're in development mode (import.meta.env.DEV === true)
• Check that the Redux DevTools extension is installed and enabled
• Refresh the page after installing the extension

Stores Not Appearing in Dropdown

• Verify that the stores are being used in the application
• Check that the devtools middleware is properly configured
• Ensure store names are unique and descriptive

Performance Issues

• DevTools can impact performance in development
• Disable DevTools for specific stores if needed by setting enabled: false
• Use the "Skip" feature in DevTools to ignore certain actions

Advanced Configuration

Custom DevTools Configuration

You can customize DevTools behavior per store:

devtools(
  // ... store implementation
  {
    name: 'MyStore',
    enabled: import.meta.env.DEV,
    // Additional options:
    // trace: true, // Enable stack traces
    // traceLimit: 25, // Limit stack trace depth
  },
);

Disabling DevTools for Specific Stores

If you need to disable DevTools for a specific store:

devtools(
  // ... store implementation
  {
    name: 'MyStore',
    enabled: false, // Disable DevTools
  },
);

Related Documentation

• Zustand DevTools Middleware
• Redux DevTools Extension
• Zustand Documentation