electron/.github/copilot-instructions.md

Copilot Instructions for Electron

Build System

Electron uses @electron/build-tools (e CLI). Install with npm i -g @electron/build-tools.

e sync              # Fetch sources and apply patches
e build             # Build Electron (GN + Ninja)
e build -k 999      # Build, continuing through errors
e start             # Run built Electron
e start --version   # Verify Electron launches
e test              # Run full test suite
e debug             # Run in debugger (lldb on macOS, gdb on Linux)

Linting

npm run lint              # Run all linters (JS, C++, Python, GN, docs)
npm run lint:js           # JavaScript/TypeScript only
npm run lint:clang-format # C++ formatting only
npm run lint:cpp          # C++ linting only
npm run lint:docs         # Documentation only

Running a Single Test

npm run test -- -g "pattern"   # Run tests matching a regex pattern
# Example: npm run test -- -g "ipc"

Running a Single Node.js Test

node script/node-spec-runner.js parallel/test-crypto-keygen

Architecture

Electron embeds Chromium (rendering) and Node.js (backend) to enable desktop apps with web technologies. The parent directory (../) is the Chromium source tree.

Process Model

Electron has two primary process types, mirroring Chromium:

• Main process (shell/browser/ + lib/browser/): Controls app lifecycle, creates windows, system APIs
• Renderer process (shell/renderer/ + lib/renderer/): Runs web content in BrowserWindows

Native ↔ JavaScript Bridge

Each API is implemented as a C++/JS pair:

• C++ side: shell/browser/api/electron_api_{name}.cc/.h — uses gin::Wrappable and ObjectTemplateBuilder
• JS side: lib/browser/api/{name}.ts — exports the module, registered in lib/browser/api/module-list.ts
• Binding: NODE_LINKED_BINDING_CONTEXT_AWARE(electron_browser_{name}, Initialize) in C++ and registered in shell/common/node_bindings.cc
• Type declaration: typings/internal-ambient.d.ts maps process._linkedBinding('electron_browser_{name}')

Patches System

Electron patches upstream dependencies (Chromium, Node.js, V8, etc.) rather than forking them. Patches live in patches/ organized by target, with patches/config.json mapping directories to repos.

patches/{target}/*.patch  →  [e sync]   →  target repo commits
                          ←  [e patches] ←

Key rules:

• Fix existing patches rather than creating new ones
• Preserve original authorship in TODO comments — never change TODO(name) assignees
• Each patch commit message must explain why the patch exists
• After modifying patches, run e patches {target} to export

When working on the roller/chromium/main branch for Chromium upgrades, use e sync --3 for 3-way merge conflict resolution.

Conventions

File Naming

• JS/TS files: kebab-case (file-name.ts)
• C++ files: snake_case with electron_api_ prefix (electron_api_safe_storage.cc)
• Test files: api-{module-name}-spec.ts in spec/
• Source file lists are maintained in filenames.gni (with platform-specific sections)

JavaScript/TypeScript

• Semicolons required ("semi": ["error", "always"])
• const and let only (no var)
• Arrow functions preferred
• Import order enforced: @electron/internal → @electron → electron → external → builtin → relative
• API naming: PascalCase for classes (BrowserWindow), camelCase for module APIs (globalShortcut)
• Prefer getters/setters over jQuery-style .text([text]) patterns

C++

• Follows Chromium coding style, enforced by clang-format and clang-tidy
• Uses Chromium abstractions (base::, content::, etc.)
• Header guards: #ifndef ELECTRON_SHELL_BROWSER_API_ELECTRON_API_{NAME}_H_
• Platform-specific files: _mac.mm, _win.cc, _linux.cc

Testing

• Framework: Mocha + Chai + Sinon
• Test helpers in spec/lib/ (e.g., spec-helpers.ts, window-helpers.ts)
• Use defer() from spec-helpers for cleanup, closeAllWindows() for window teardown
• Tests import from electron/main or electron/renderer

Documentation

• API docs in docs/api/ as Markdown, parsed by @electron/docs-parser to generate electron.d.ts
• API history tracked via YAML blocks in HTML comments within doc files
• Docs must pass npm run lint:docs

Build Configuration

• BUILD.gn: Main GN build config
• buildflags/buildflags.gni: Feature flags (PDF viewer, extensions, spellchecker)
• build/args/: Build argument profiles (testing.gn, release.gn, all.gn)
• DEPS: Dependency versions and checkout paths
• chromium_src/: Chromium source file overrides (compiled instead of originals)