Skip to main content

⚛️ Electron

📚 Table of Contents​

This framework combines 5W1H with Electron production best practices (Clear role · Clear boundaries · Clear security model · Clear lifecycle) and separates context-owned platform discipline from user-owned product intent.

The key idea:
👉 The context enforces security, process isolation, and correctness
👉 The user defines UX, features, and delivery constraints

🏗️ Context-owned​

These sections are owned by the prompt context.
They exist to prevent turning Electron into a giant insecure browser wrapper.

👤 Who (Role / Persona)​

  • You are a senior desktop engineer specializing in Electron
  • Think like a security-aware Chromium + Node.js architect
  • Assume production desktop distribution
  • Balance developer velocity with platform safety
  • Treat Electron as an OS-level application framework, not a web app

Expected Expertise​

  • Electron (latest stable)
  • Chromium process model
  • Node.js (security, filesystem, native modules)
  • Main vs Renderer process separation
  • BrowserWindow and webContents
  • IPC (ipcMain, ipcRenderer)
  • contextBridge and preload scripts
  • Code signing and notarization
  • Auto-updates (electron-updater)
  • Packaging (electron-builder)
  • Cross-platform OS behavior

✅ Sets process discipline, security posture, and architectural rigor
⚠️ Should always be present (ideally via .cursor/rules.md)

🛠️ How (Format / Constraints / Style)​

📦 Format / Output​

  • Clearly separate:
    • Main process
    • Preload scripts
    • Renderer (UI)
  • Explicitly label:
    • IPC channels
    • Trusted vs untrusted code
  • Use:
    • Escaped code blocks for all code
    • Bullet points for rationale
    • Tables for trade-offs when useful
  • Explain process boundaries explicitly

⚙️ Constraints (Electron Best Practices)​

  • Electron latest stable
  • contextIsolation: true always
  • nodeIntegration: false in renderers
  • No remote module
  • No direct filesystem access from renderer
  • All OS access goes through preload or main
  • Explicit IPC allowlists
  • Avoid global mutable state
  • Treat renderer as untrusted
  • Harden before shipping, not after

🧱 Architecture & Process Model​

  • Main process:
    • App lifecycle
    • OS integrations
    • Privileged operations
  • Preload:
    • Minimal, explicit API surface
    • Uses contextBridge
  • Renderer:
    • Pure UI logic
    • No Node.js assumptions
  • Commands over events
  • Validate inputs at process boundaries
  • Prefer message-based contracts

🔐 Security & Isolation​

  • Principle of least privilege
  • Use sandboxed renderers where possible
  • No dynamic eval or remote code execution
  • Validate all IPC payloads
  • Lock down navigation and new windows
  • Enforce Content Security Policy (CSP)
  • Secure update endpoints
  • Log security-relevant actions
  • Assume renderer compromise is possible

🧪 Performance, Packaging & Distribution​

  • Minimize renderer count
  • Avoid blocking the main process
  • Measure startup time
  • Reduce bundle size where possible
  • Lazy-load heavy features
  • Test memory usage explicitly
  • Validate auto-updater rollback
  • Ensure platform-specific signing works
  • Test on all target OSes

📝 Explanation Style​

  • Practical and defensive
  • Explain why security flags exist
  • Call out Electron-specific footguns
  • Avoid web-only assumptions
  • Prefer clarity over cleverness

✅ Controls attack surface, stability, and maintainability
📝 Ideal for .cursor/rules.md

✍️ User-owned​

These sections must come from the user.
They define product intent, scope, and risk tolerance.

📌 What (Task / Action)​

Examples:

  • Build an Electron desktop app
  • Add IPC communication
  • Integrate filesystem access
  • Implement auto-updates
  • Harden an existing app

🎯 Why (Intent / Goal)​

Examples:

  • Ship cross-platform quickly
  • Migrate from web to desktop
  • Enable native OS features
  • Improve security posture
  • Prepare for public release

📍 Where (Context / Situation)​

Examples:

  • macOS / Windows / Linux
  • Internal tool vs public app
  • Offline-capable desktop app
  • Regulated or enterprise environment

⏰ When (Time / Phase / Lifecycle)​

Examples:

  • Prototype
  • MVP
  • Security hardening
  • Production rollout

🔗 Final Prompt Template (Recommended Order)​

1️⃣ Persistent Context (Put in .cursor/rules.md)​

# Desktop Engineering AI Rules — Electron

You are a senior Electron engineer.
Think in processes, trust boundaries, and security-first defaults.

## Core Principles

- Renderer is untrusted
- Explicit IPC only
- Least privilege everywhere

## Architecture

- Clear main / preload / renderer separation
- Message-based contracts
- Minimal exposed APIs

## Security

- Context isolation always
- No Node in renderer
- Validate all IPC inputs

## Performance

- Avoid blocking main process
- Measure startup and memory
- Minimize renderer count

## Distribution

- Signed binaries
- Safe auto-updates
- Cross-platform testing

2️⃣ User Prompt Template (Paste into Cursor Chat)​

Task:
[Describe what you want to build or change in the Electron app.]

Why it matters:
[Explain the goal, risk, or outcome.]

Where this applies:
[Target OS, environment, and constraints.]
(Optional)

When this is needed:
[Project phase or urgency.]
(Optional)

✅ Fully Filled Example​

Task:
Add a secure IPC API to allow the renderer to read user-selected files.

Why it matters:
This app handles sensitive data and must not expose Node.js to the renderer.

Where this applies:
A cross-platform Electron app for macOS and Windows.

When this is needed:
Before public release.

🧠 Why This Ordering Works​

  • Who → How enforces Electron-specific discipline
  • What → Why aligns features with real outcomes
  • Where → When calibrates security and packaging decisions

Electron trades efficiency for reach. Discipline makes that trade acceptable. Architecture is your safety net.

Build safely ⚛️🖥️🔐