CLAUDE.md

1# Electron Development Guide
2 
3## Running node_modules binaries
4 
5**Never use `npx`.** It is considered dangerous because it can silently fetch and execute arbitrary packages from the registry. Always run binaries through one of these safer mechanisms instead:
6 
71. **Preferred** — spawn the executable directly from `node_modules/.bin/<tool>` (or the platform equivalent on Windows). This is what `script/lint.js` does for `oxlint`.
82. **Acceptable** — invoke via `yarn <tool>` or `yarn run <tool>`, which resolves to the locally installed version without the registry fallback that `npx` performs.
9 
10This rule applies to shell commands you run yourself and to any scripts you author or modify in this repo.
11 
12## Project Overview
13 
14Electron is a framework for building cross-platform desktop applications using web technologies. It embeds Chromium for rendering and Node.js for backend functionality.
15 
16## Directory Structure
17 
18```text
19electron/                 # This repo (run `e` commands here)
20├── shell/               # Core C++ application code
21│   ├── browser/         # Main process implementation (107+ API modules)
22│   ├── renderer/        # Renderer process code
23│   ├── common/          # Shared code between processes
24│   ├── app/             # Application entry points
25│   └── services/        # Node.js service integration
26├── lib/                 # TypeScript/JavaScript library code
27│   ├── browser/         # Main process JS (47 API implementations)
28│   ├── renderer/        # Renderer process JS
29│   └── common/          # Shared JS modules
30├── patches/             # Patches for upstream dependencies
31│   ├── chromium/        # ~159 patches to Chromium
32│   ├── node/            # ~48 patches to Node.js
33│   └── ...              # Other targets (v8, boringssl, etc.)
34├── spec/                # Test suite (1189+ TypeScript test files)
35├── docs/                # API documentation and guides
36├── build/               # Build configuration
37├── script/              # Build and automation scripts
38└── chromium_src/        # Chromium source overrides
39../                      # Parent directory is Chromium source
40```
41 
42## Build Tools Setup
43 
44Electron uses `@electron/build-tools` for development. The `e` command is the primary CLI.
45 
46**Installation:**
47 
48```bash
49npm i -g @electron/build-tools
50```
51 
52**Configuration location:** `~/.electron_build_tools/configs/`
53 
54## Essential Commands
55 
56### Configuration Management
57 
58| Command | Purpose |
59|---------|---------|
60| `e init <name> --root=<path> --bootstrap testing` | Create new build config and sync |
61| `e use <name>` | Switch to a different build configuration |
62| `e show current` | Display active configuration name |
63| `e show configs` | List all available configurations |
64 
65### Build & Development Loop
66 
67| Command | Purpose |
68|---------|---------|
69| `e sync` | Fetch/update all source code and apply patches |
70| `e sync --3` | Sync with 3-way merge (required for Chromium upgrades) |
71| `e build` | Build Electron (runs GN + Ninja) |
72| `e build -k 999` | Build and continue on errors (up to 999) |
73| `e build -t <target>` | Build specific target (e.g., `electron:node_headers`) |
74| `e start` | Run the built Electron executable |
75| `e start --version` | Verify Electron launches and print version |
76| `e test` | Run the test suite |
77| `e debug` | Run Electron in debugger (lldb on macOS, gdb on Linux) |
78 
79### Patch Management
80 
81| Command | Purpose |
82|---------|---------|
83| `e patches <target>` | Export patches for a target (chromium, node, v8, etc.) |
84| `e patches all` | Export all patches from all targets |
85| `e patches --list-targets` | List available patch targets |
86 
87## Typical Development Workflow
88 
89```bash
90# 1. Ensure you're on the right config
91e show current
92 
93# 2. Sync to get latest code
94e sync
95 
96# 3. Make your changes in shell/ or lib/ or ../
97 
98# 4. Build
99e build
100 
101# 5. Test your changes (Leave the user to do this, don't run these commands unless asked)
102e start
103e test
104 
105# 6. If you modified patched files in Chromium:
106cd ..  # Go to Chromium repo
107git add &lt;files&gt;
108git commit -m &quot;description of change&quot;
109cd electron
110e patches chromium  # Export the patch
111```
112 
113## Patches System
114 
115Electron patches upstream dependencies (Chromium, Node.js, V8, etc.) to add features or modify behavior.
116 
117**How patches work:**
118 
119```text
120patches/{target}/*.patch  →  [e sync --3]  →  target repo commits
121                          ←  [e patches]   ←
122```
123 
124**Patch configuration:** `patches/config.json` maps patch directories to target repos.
125 
126**Key rules:**
127 
128- Fix existing patches 99% of the time rather than creating new ones
129- Preserve original authorship in TODO comments
130- Never change TODO assignees (`TODO(name)` must retain original name)
131- Each patch file includes commit message explaining its purpose
132 
133**Creating/modifying patches:**
134 
1351. Make changes in the target repo (e.g., `../` for Chromium)
1362. Create a git commit
1373. Run `e patches <target>` to export
138 
139**Fixing patch conflicts on an existing PR:**
140 
141If asked to fix a patch conflict on a branch that already has an open PR, check the PR's failed **Apply Patches** CI run for an `update-patches` artifact before running `e sync` locally. CI has already performed the 3-way merge and exported the resolved patch diff — applying it is much faster than a full local sync.
142 
143```bash
144# Find the failed Apply Patches run for the PR and download the artifact
145gh run list --repo electron/electron --branch &lt;pr-branch&gt; --workflow &quot;Apply Patches&quot; --limit 1
146gh run download &lt;run-id&gt; --repo electron/electron --name update-patches
147 
148# Apply the CI-generated fix, then push
149git am update-patches.patch
150git push
151```
152 
153If no artifact exists (e.g. the 3-way merge itself failed), fall back to `e sync --3` and resolve manually.
154 
155## Testing
156 
157**Test location:** `spec/` directory
158 
159**Running tests:**
160 
161```bash
162e test                    # Run full test suite
163```
164 
165**Test frameworks:** Mocha, Chai, Sinon
166 
167## Build Configuration
168 
169**GN build arguments:** Located in `build/args/`:
170 
171- `testing.gn` - Debug/testing builds
172- `release.gn` - Release builds
173- `all.gn` - Common arguments for all builds
174 
175**Main build file:** `BUILD.gn`
176 
177**Feature flags:** `buildflags/buildflags.gni`
178 
179## Chromium Upgrade Workflow
180 
181When working on the `roller/chromium/main` branch to upgrade Chromium activate the "Electron Chromium Upgrade" skill.
182 
183## Node.js Upgrade Workflow
184 
185When working on the `roller/node/main` branch to upgrade Node.js activate the "Electron Node.js Upgrade" skill.
186 
187## Pull Requests
188 
189PR bodies must always include a `Notes:` section as the **last line** of the body. This is a consumer-facing release note for Electron app developers — describe the user-visible fix or change, not internal implementation details. Use `Notes: none` if there is no user-facing change.
190 
191### PR Labeling (write-access only)
192 
193When the user has write access to `electron/electron`, add these labels when creating PRs:
194 
195**Semver label** — one of:
196 
197- `semver/none` — build changes, refactors, CI, or anything with no end-user impact
198- `semver/patch` — backwards-compatible bug fixes
199- `semver/minor` — backwards-compatible new functionality
200- `semver/major` — incompatible API changes
201 
202**Backport target labels** — add `target/{N}-x-y` for each supported release branch the change should land on. Default policy:
203 
204- **Bug fixes** — backport to all active release lines _except the oldest_
205- **Security fixes** — backport to all active release lines _including the oldest_
206- **Features (semver/minor) and breaking changes (semver/major)** — no backport labels; main-only by default
207 
208To find which release branches are active, check label colors — active `target/*` labels use color `#ad244f`, older/EOL ones use `#ededed`:
209 
210```bash
211gh label list --repo electron/electron --search target/ --json name,color --jq '.[] | select(.color == "ad244f") | .name'
212```
213 
214## Code Style
215 
216**C++:** Follows Chromium style, enforced by clang-format
217**TypeScript/JavaScript:** [oxlint](https://oxc.rs/docs/guide/usage/linter) configuration in `.oxlintrc.json`
218 
219**Linting:**
220 
221```bash
222npm run lint              # Run all linters
223npm run lint:js           # Run oxlint over all JS/TS/MJS sources
224npm run lint:clang-format # C++ formatting
225npm run lint:api-history  # Validate API history YAML blocks in docs
226```
227 
228## Key Files
229 
230| File | Purpose |
231|------|---------|
232| `BUILD.gn` | Main GN build configuration |
233| `DEPS` | Dependency versions and checkout paths |
234| `patches/config.json` | Patch target configuration |
235| `filenames.gni` | Source file lists by platform |
236| `package.json` | Node.js dependencies and scripts |
237 
238## Environment Variables
239 
240| Variable | Purpose |
241|----------|---------|
242| `GN_EXTRA_ARGS` | Additional GN arguments (useful in CI) |
243| `ELECTRON_RUN_AS_NODE=1` | Run Electron as Node.js |
244 
245## Useful Git Commands for Chromium
246 
247```bash
248# Find CL that changed a file
249cd ..
250git log --oneline -10 -- {file}
251git blame -L {start},{end} -- {file}
252 
253# Look for Chromium CL reference in commit
254git log -1 {commit_sha}  # Find "Reviewed-on:" line
255 
256# Find which patch affects a file
257grep -l &quot;filename.cc&quot; patches/chromium/*.patch
258```
259 
260## CI/CD
261 
262GitHub Actions workflows in `.github/workflows/`:
263 
264- `build.yml` - Main build workflow
265- `pipeline-electron-lint.yml` - Linting
266- `pipeline-segment-electron-test.yml` - Testing
267 
268## Common Issues
269 
270**Patch conflict during sync:**
271 
272- Use `e sync --3` for 3-way merge
273- Check if file was renamed/moved upstream
274- Verify patch is still needed
275 
276**Build error in patched file:**
277 
278- Find the patch: `grep -l "filename" patches/chromium/*.patch`
279- Match existing patch style (#if 0 guards, BUILDFLAG conditionals, etc.)
280 
281**Remote build issues:**
282 
283- Try `e build --no-remote` to build locally
284- Check reclient/siso configuration in your build config
285