electron-dev

What this skill does

# Electron Development

Build production-ready Electron applications with security-first architecture, optimal performance, and excellent user experience.

## When to Use This Skill

Use this skill when you need to:
- Create new Electron applications from scratch
- Implement secure IPC communication between main and renderer processes
- Add file system operations (read, write, watch, drag & drop)
- Integrate system features (tray icons, global shortcuts, notifications)
- Manage windows (multi-window, frameless, modal dialogs)
- Optimize application performance
- Integrate React or Vue frameworks with Electron
- Follow Electron security best practices

## Quick Start

### Creating a New Project

For a complete, production-ready Electron project with all best practices:

```bash
# Copy the vanilla template to your working directory
cp -r assets/vanilla-template/* /path/to/your/project

# Install dependencies
cd /path/to/your/project
npm install

# Start development
npm run dev
```

The template includes:
- ✅ Secure main process with proper configuration
- ✅ Context-isolated preload script
- ✅ Example renderer with file operations, window controls, notifications
- ✅ System tray integration
- ✅ Global keyboard shortcuts
- ✅ Comprehensive comments explaining every best practice
- ✅ Cross-platform build configuration

### For Framework-Specific Projects

If you need React or Vue integration, consult `references/framework-guides.md` first for detailed setup instructions, then use the vanilla template as a reference for security and IPC patterns.

## Core Capabilities

### 1. Secure Architecture

Every code template in this skill implements Electron's security best practices:

**Security settings (always applied):**
```javascript
webPreferences: {
  contextIsolation: true,    // Isolates renderer from main process
  nodeIntegration: false,     // Prevents Node.js access in renderer
  sandbox: true,              // Sandboxes renderer process
  preload: path.join(__dirname, 'preload.js'),
}
```

**Why this matters:** These settings prevent remote code execution, protect against XSS attacks, and ensure malicious web content can't access system resources.

For comprehensive security guidance, see `references/security-guide.md`.

### 2. IPC Communication Patterns

All IPC communication goes through validated channels in the preload script:

**Three main patterns:**
1. **Request-Response** (invoke/handle): For operations that need a return value
2. **One-Way** (send/on): For notifications and events
3. **Streaming**: For real-time updates like file watching

Each pattern includes:
- Input validation in both preload and main process
- Structured error handling
- Proper cleanup functions
- Performance optimizations

For detailed IPC patterns and examples, see `references/ipc-patterns.md`.

### 3. File System Operations

The vanilla template demonstrates:
- Opening files via native dialog
- Reading file contents securely
- Writing files with user confirmation
- Watching files for changes
- Drag & drop support with visual feedback

All file operations include:
- Path validation (prevent path traversal)
- Error handling with user-friendly messages
- Performance considerations (streaming for large files)
- Cross-platform compatibility

### 4. System Integration

Templates show how to implement:
- **System tray**: With context menu and click handlers
- **Global shortcuts**: Cross-platform keyboard shortcuts
- **Native notifications**: With click handlers
- **Window management**: Minimize, maximize, close, multi-window
- **Custom title bars**: For frameless windows

All system integrations include platform-specific handling for macOS, Windows, and Linux.

### 5. Performance Optimization

Code templates implement performance best practices:
- Lazy window loading (show only when ready)
- Debouncing frequent operations
- Proper memory cleanup
- Efficient IPC batching
- Hardware acceleration

For comprehensive performance tips, see `references/performance-tips.md`.

## Workflow

### For New Projects

1. **Choose your framework**
   - Vanilla JavaScript: Use `assets/vanilla-template/` directly
   - React/Vue: Read `references/framework-guides.md` then adapt patterns

2. **Copy template to your project directory**
   ```bash
   cp -r assets/vanilla-template/* /your/project/
   ```

3. **Install dependencies**
   ```bash
   cd /your/project
   npm install
   ```

4. **Customize for your needs**
   - Update `package.json` (name, description, build config)
   - Modify UI in `src/renderer/`
   - Add IPC handlers in `src/main/main.js`
   - Expose APIs in `src/preload/preload.js`

5. **Test in development**
   ```bash
   npm run dev
   ```

6. **Build for distribution**
   ```bash
   npm run build          # All platforms
   npm run build:mac      # macOS only
   npm run build:win      # Windows only  
   npm run build:linux    # Linux only
   ```

### For Adding Features to Existing Projects

1. **Identify the feature type**
   - File operations → See template's file handling code
   - IPC communication → Check `references/ipc-patterns.md`
   - System integration → Review tray/shortcut examples
   - Performance issues → Consult `references/performance-tips.md`

2. **Find relevant code in template**
   - `src/main/main.js`: Main process examples
   - `src/preload/preload.js`: Secure API exposure
   - `src/renderer/renderer.js`: Renderer-side usage

3. **Copy and adapt the pattern**
   - All code includes detailed comments explaining why and how
   - Security and performance best practices are embedded
   - Cross-platform considerations are noted

4. **Test thoroughly**
   - Test on all target platforms
   - Verify security settings
   - Check performance with real data

## Code Examples

All code examples in this skill follow these principles:

**1. Comments explain WHY, not just WHAT**
```javascript
// ❌ BAD comment
// Create window
const win = new BrowserWindow({ show: false });

// ✅ GOOD comment (from template)
// UX: Hide window initially to prevent flickering
// Show only when ready-to-show event fires
const win = new BrowserWindow({ show: false });
```

**2. Security is non-negotiable**
```javascript
// Every IPC handler validates input
ipcMain.handle('file:read', async (event, filePath) => {
  // SECURITY: Validate that the path is absolute to prevent path traversal
  if (!path.isAbsolute(filePath)) {
    throw new Error('File path must be absolute');
  }
  // ... rest of implementation
});
```

**3. Performance is considered**
```javascript
// Debounce frequent operations
let debounceTimer;
ipcMain.handle('search', async (event, query) => {
  return new Promise((resolve) => {
    clearTimeout(debounceTimer);
    debounceTimer = setTimeout(async () => {
      const results = await searchDatabase(query);
      resolve(results);
    }, 300);
  });
});
```

**4. Cross-platform compatibility**
```javascript
// PLATFORM SPECIFIC: Handle tray click differently on different platforms
tray.on('click', () => {
  if (process.platform === 'win32') {
    // Windows: Click to show/hide
    mainWindow.isVisible() ? mainWindow.hide() : mainWindow.show();
  }
  // macOS: Tray doesn't typically toggle window visibility
});
```

## Reference Documentation

This skill includes comprehensive reference guides:

### references/ipc-patterns.md
Complete guide to IPC communication patterns:
- Request-response (invoke/handle)
- One-way communication (send/on)
- Streaming data
- Input validation strategies
- Channel whitelisting
- Error handling patterns
- Performance optimization
- Common pitfalls to avoid

**When to read**: Implementing any communication between main and renderer processes.

### references/security-guide.md
Comprehensive security best practices:
- Configuration checklist
- Content Security Policy setup
- Input validation (file paths, URLs, commands)
- Navigation and window security
- Safe handling of remote content
- Secure updates with code signing
- Dependency security
- Encrypt