Electron Package Documentation

Desktop notification support for Electron applications with system notifications and unified service integration. This package provides comprehensive desktop notification capabilities for Windows, macOS, and Linux.

Installation

npm install @sparkstrand/notifications-electron

This package requires @sparkstrand/notifications-core as a peer dependency and integrates with the unified notification service.

Setting Up Your App

App Registration

Before using notifications, your Electron app must register with the notification service using your own provider API keys. This ensures complete isolation from other applications.

// In your main process initialization
import {notificationService} from '@sparkstrand/notifications-core';

await notificationService.registerApp({
  appId: 'venture-direction',
  name: 'VentureDirection',
  providers: {
    novu: {
      apiKey: process.env.VENTURE_DIRECTION_NOVU_API_KEY,
      appId: process.env.VENTURE_DIRECTION_NOVU_APP_ID,
      priority: 1
    },
    resend: {
      apiKey: process.env.VENTURE_DIRECTION_RESEND_API_KEY,
      fromEmail: 'notifications@venturedirection.com',
      priority: 2
    }
  }
});

Provider Configuration

Each app manages its own provider credentials:

  • • Novu: For push notifications, in-app notifications, and multi-channel delivery
  • • Resend: For direct email delivery with custom templates
  • • Twilio: For SMS notifications (when implemented)
  • • Custom providers: Add your own notification providers

Key Features

  • • System Notifications: Native OS notifications for Windows, macOS, and Linux
  • • Cross-Platform Support: Consistent API across all operating systems
  • • Notification Actions: Custom action buttons and quick replies
  • • Sound & Vibration: Custom notification sounds and haptic feedback
  • • Rich Content: Support for images, HTML content, and custom styling
  • • Notification Center Integration: Seamless integration with OS notification centers
  • • Unified Service Integration: Seamless integration with the notification service
  • • TypeScript Support: Full type safety and IntelliSense

Core Functions

setupNotifications

Initialize the notification system in your Electron app's main process.

import {setupNotifications} from '@sparkstrand/notifications-electron';

// In your main process
app.whenReady().then(() => {
  setupNotifications({
    appName: 'VentureDirection',
    icon: path.join(__dirname, 'assets/icon.png'),
    defaultSound: true
  });
});

showSystemNotification

Display a system notification with custom content and actions.

import {showSystemNotification} from '@sparkstrand/notifications-electron';

await showSystemNotification({
  title: 'New Message',
  body: 'You have a new message from John Doe',
  icon: path.join(__dirname, 'assets/message-icon.png'),
  actions: [
    { text: 'Reply', type: 'button' },
    { text: 'Mark as Read', type: 'button' }
  ],
  onClick: () => { /* Handle click */ },
  onAction: (action) => { /* Handle action */ }
});

useNotifications

React hook for managing notifications in your renderer process.

import {useNotifications} from '@sparkstrand/notifications-electron';

function NotificationComponent() {
  const {
    notifications,
    unreadCount,
    markAsRead,
    deleteNotification
  } = useNotifications();

  return (
    <div>Unread: {unreadCount}</div>
  );
}

System Notifications

Platform-Specific Features

Windows

  • • Toast notifications
  • • Action center integration
  • • Custom sounds
  • • Rich content support

macOS

  • • Notification Center
  • • Banner and alert styles
  • • Action button support
  • • Sound customization

Linux

  • • Desktop notifications
  • • Multiple backends
  • • Custom actions
  • • Sound support

Notification Options

interface NotificationOptions {
  title: string;
  body: string;
  icon?: string;
  badge?: string;
  tag?: string;
  silent?: boolean;
  sound?: string;
  actions?: NotificationAction[];
  onClick?: () => void;
  onClose?: () => void;
  onAction?: (action: NotificationAction) => void;
}

Usage Examples

Basic Setup

// main.js
import {app} from 'electron';
import {setupNotifications} from '@sparkstrand/notifications-electron';

app.whenReady().then(() => {
  setupNotifications({
    appName: 'MyApp',
    icon: path.join(__dirname, 'assets/icon.png')
  });
});

Sending Notifications

// In your main process
import {showSystemNotification} from '@sparkstrand/notifications-electron';

// Send via unified service
await notificationService.sendNotification(
  'user-123',
  'INFO',
  'New Update Available',
  'Version 2.0 is ready to download',
  { email: 'user@example.com' },
  { appId: 'venture-direction', channels: { inApp: true } }
);

// Show system notification
await showSystemNotification({
  title: 'New Update Available',
  body: 'Version 2.0 is ready to download',
  actions: [
    { text: 'Download Now', type: 'button' },
    { text: 'Later', type: 'button' }
  ]
});

Renderer Process Integration

// renderer.js
import {useNotifications} from '@sparkstrand/notifications-electron';

function App() {
  const {notifications, unreadCount} = useNotifications();

  return (
    <div>
      <h1>Notifications ({unreadCount})</h1>
      {notifications.map(n => (
        <div key={n.id}>{n.title}</div>
      ))}
    </div>
  );
}

Customization

Styling & Theming

Customize the appearance and behavior of notifications:

  • • Custom Icons: Set app-specific notification icons
  • • Sound Customization: Custom notification sounds per notification type
  • • Action Buttons: Custom action buttons with specific behaviors
  • • Notification Duration: Control how long notifications are displayed
  • • Position Control: Customize notification positioning on screen

Platform-Specific Features

Windows

  • • Toast notification API
  • • Action center integration
  • • Custom sound files
  • • Rich content with images
  • • Notification grouping

macOS

  • • Notification Center API
  • • Banner and alert styles
  • • Action button support
  • • Sound customization
  • • Do Not Disturb integration

Testing

Testing Notifications

Test your notification system across different platforms:

  • • Cross-Platform Testing: Test on Windows, macOS, and Linux
  • • Notification Center: Verify notifications appear in OS notification centers
  • • Action Testing: Test custom action buttons and click handlers
  • • Sound Testing: Verify custom sounds work correctly
  • • Integration Testing: Test with the unified notification service

Best Practices

  • • Register early: Register your app during Electron app initialization
  • • Platform awareness: Test notifications on all target platforms
  • • User preferences: Respect user notification preferences and Do Not Disturb settings
  • • Action handling: Implement proper handlers for notification actions
  • • Error handling: Handle notification failures gracefully
  • • Performance: Avoid showing too many notifications simultaneously
  • • Accessibility: Ensure notifications are accessible to screen readers