@zubridge/electron

Zubridge Electron

Cross-platform state without boundaries: Zustand-inspired simplicity for Electron

Why Zubridge?

tldr: I want to seamlessly interact with my main process state using Zustand-inspired hooks.

Zustand is a great state management library that, like Redux, recommends using a single store for your application. However, in Electron apps, this approach faces challenges when state needs to be accessed across process boundaries.

@zubridge/electron solves this by enabling a single store workflow, abstracting away the IPC management and state synchronization between processes.

How It Works

Zubridge creates a bridge between your main process state and your renderer processes. The main process state acts as the single source of truth, while renderer processes receive synchronized copies of the state through a Zustand-like interface.

Actions from renderer processes are sent through IPC to the main process, which updates the central state. These updates are then automatically broadcast to all connected renderer processes, ensuring consistent state throughout your application.

Features

• Zustand-like API for state management across main and renderer processes
• Frontend flexibility - works with React, other frontend frameworks, or vanilla JavaScript
• Choice of state management solutions:
  • Zustand adapter with support for store handlers, separate handlers, and Redux-style reducers
  • Redux adapter for Redux/Redux Toolkit integration
  • Generic bridge for creating custom state management implementations
• Type-safe state management between processes
  • Enhanced TypeScript integration with typed action objects for auto-completion and type-checking
• Automatic state synchronization across multiple windows
• Support for multiple windows and views
• Works with the latest Electron security recommendations
• Rich action support including thunks, inline actions, and action objects in both processes
• Automatic cleanup for destroyed windows and error recovery

Installation

npm install @zubridge/electron zustand

Or use your dependency manager of choice, e.g. pnpm, yarn.

Quick Start

• Create a Zustand store in your main process
• Initialize the bridge with your store and windows
• Use the createUseStore function to create a hook for accessing the store in your renderer process

Documentation

• Getting Started Guide - Step-by-step guide to setting up Zubridge in your Electron app
• Advanced Usage - Advanced features including multi-window support, custom handlers, and more
• Main Process - Setting up and using Zubridge in the main process
• Renderer Process - Setting up and using Zubridge in the renderer process
• Backend Contract - Understanding the IPC contract between processes
• Debugging - Using the debug utilities to troubleshoot and monitor Zubridge
• API Reference - Complete API documentation

Example Applications

The example apps demonstrate different approaches to using zubridge with Electron:

• Custom Example - Custom state manager implementation using createCoreBridge
• Redux Example - Redux with Redux Toolkit using createReduxBridge
• Zustand Basic Example - Zustand with direct store mutations using createZustandBridge
• Zustand Handlers Example - Zustand with dedicated action handler functions using createZustandBridge
• Zustand Reducers Example - Zustand with Redux-style reducers using createZustandBridge
• Zustand Immer Example - Zustand with Immer middleware for immutable updates using createZustandBridge

Special Configuration Examples

• Context Isolation Disabled - Example showing Zubridge usage with contextIsolation: false (legacy apps only, not recommended for new projects)

Debugging

Zubridge includes a built-in debugging utility that allows you to control logging across different parts of the package. This is separate from the middleware logging which focuses on IPC traffic.

Enabling Debug Mode

Zubridge uses the popular debug package for debugging. You can enable it in several ways:

• Using the DEBUG environment variable:

  # Enable all Zubridge debugging
  DEBUG=zubridge:* electron .
  
  # Enable specific debug areas only
  DEBUG=zubridge:ipc,zubridge:core electron .
  

• Using the ZUBRIDGE_DEBUG environment variable:

  # Enable all debugging
  ZUBRIDGE_DEBUG=true electron .
  

• Programmatically:

  import { debug } from '@zubridge/core';
  
  // Enable all debugging
  debug.enable();
  
  // Enable debugging for specific areas
  debug.enable(['ipc', 'core']);
  
  // Disable debugging
  debug.disable();
  

Debug Areas

The following debug namespaces are available:

• zubridge:core: Core bridge functionality
• zubridge:ipc: IPC communication between processes
• zubridge:store: Store management
• zubridge:adapters: Zustand and Redux adapters
• zubridge:windows: Window management
• zubridge:serialization: State serialization/deserialization

Browser Integration

For debugging in the renderer process, you can use the browser's localStorage:

// In the DevTools console
localStorage.debug = 'zubridge:*'; // Enable all debugging
localStorage.debug = ''; // Disable debugging

For more detailed information, see the Debugging documentation.

Development

For information about contributing to this project, see the Developer Guide.

License

MIT