mirror of
https://github.com/electron/electron.git
synced 2026-04-10 03:01:51 -04:00
123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# Copilot Instructions for Electron
|
|
|
|
## Build System
|
|
|
|
Electron uses `@electron/build-tools` (`e` CLI). Install with `npm i -g @electron/build-tools`.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
npm run test -- -g "pattern" # Run tests matching a regex pattern
|
|
# Example: npm run test -- -g "ipc"
|
|
```
|
|
|
|
### Running a Single Node.js Test
|
|
|
|
```bash
|
|
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.
|
|
|
|
```text
|
|
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)
|