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:

# 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):

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:

Request-Response (invoke/handle): For operations that need a return value
One-Way (send/on): For notifications and events
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

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

Copy template to your project directory

cp -r assets/vanilla-template/* /your/project/

Install dependencies
```
cd /your/project
npm install
```
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
Test in development
```
npm run dev
```

Build for distribution

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

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

// ❌ 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

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

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

// 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
Encryption for sensitive data
Production security checklist

When to read: Before releasing to production, when handling user input, or dealing with external content.

references/performance-tips.md

Performance optimization techniques:

Startup optimization
Main process performance
Renderer process optimization
Memory management
IPC performance
GPU acceleration
Network optimization
Profiling tools and techniques

When to read: When experiencing performance issues or optimizing for production.

references/framework-guides.md

Integrating popular frameworks:

React setup and configuration
Vue integration
TypeScript support
State management (Redux, Pinia)
Build process and hot reload
Common issues and solutions

When to read: Building with React, Vue, or TypeScript.

Project Templates

assets/vanilla-template/

Complete Electron project with vanilla HTML/CSS/JavaScript:

Structure:

vanilla-template/
├── src/
│   ├── main/
│   │   └── main.js           # Main process with all features
│   ├── preload/
│   │   └── preload.js        # Secure IPC bridge
│   └── renderer/
│       ├── index.html        # UI with examples
│       ├── styles.css        # Modern styling
│       └── renderer.js       # Event handlers and logic
├── package.json              # Dependencies and build config
├── README.md                 # Project documentation
└── .gitignore

Features demonstrated:

✅ File operations (open, read, write, watch)
✅ Drag & drop support
✅ Window controls (minimize, maximize, close)
✅ System tray with context menu
✅ Global keyboard shortcuts
✅ Native notifications
✅ Custom title bar
✅ Cross-platform build configuration
✅ Development and production modes

Every file includes:

Detailed comments explaining best practices
Security considerations marked with "SECURITY:"
Performance tips marked with "PERFORMANCE:"
UX improvements marked with "UX:"
Platform-specific code marked with "PLATFORM SPECIFIC:"

Best Practices Summary

The code in this skill embodies these principles:

Security (CRITICAL):

✅ Always use contextIsolation: true
✅ Always use nodeIntegration: false
✅ Always validate inputs in main process
✅ Never expose full Node.js/Electron APIs to renderer
✅ Use Content Security Policy

Performance:

✅ Show windows only when ready
✅ Debounce/throttle frequent operations
✅ Batch IPC calls when possible
✅ Clean up event listeners
✅ Use streaming for large files

User Experience:

✅ Provide visual feedback for async operations
✅ Handle errors gracefully with user-friendly messages
✅ Support keyboard shortcuts
✅ Smooth window transitions
✅ Platform-appropriate behavior

Code Quality:

✅ Modular, well-organized code structure
✅ Comprehensive error handling
✅ Clear, informative comments
✅ Consistent naming conventions
✅ Cross-platform compatibility

Common Tasks

Adding a New IPC Handler

Add handler in main process (src/main/main.js)
Expose in preload script (src/preload/preload.js)
Use in renderer (src/renderer/renderer.js)

Example in template shows complete pattern with validation and error handling.

Implementing File Operations

See the file operations section in vanilla template:

Dialog-based file selection
Secure file reading/writing
File watching for real-time updates
Drag & drop support

Creating Multi-Window Applications

Use the createChildWindow function in the template as a starting point. Supports:

Parent-child window relationships
Modal dialogs
Independent windows

Cross-Platform Building

Build configuration in package.json handles:

macOS: DMG and ZIP
Windows: NSIS installer and portable
Linux: AppImage and DEB package

Troubleshooting

Common issues and solutions:

White screen in production:

Ensure paths are correct for packaged app
Set homepage: "./" in package.json

IPC not working:

Check contextBridge is exposing APIs correctly
Verify channel names match between main and preload

Performance issues:

Profile with Chrome DevTools
Check for memory leaks (event listeners not cleaned up)
Consider using utility processes for heavy work

Security warnings:

Review security checklist in references/security-guide.md
Ensure all security settings are enabled
Validate all user inputs

For detailed troubleshooting, consult the reference documentation.

Next Steps

After creating your Electron app:

Test thoroughly on all target platforms
Review security checklist before production
Optimize performance using profiling tools
Set up auto-updates with electron-updater
Configure code signing for distribution
Consider error tracking for production monitoring

This skill provides the foundation for professional Electron development. All code is production-ready and follows industry best practices.

electron-dev