Online/offline detection in main process
In the main process, use the net.isOnline() method or the net.online property to detect online and offline status.
main process modules & overview
25 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
net.isOnline() and net.online reliability
Both net.isOnline() and net.online return the same boolean value with the same reliability characteristics as navigator.onLine. They provide a strong indicator when offline (false), but a true value does not guarantee successful internet connectivity.
net module availability
The net module is only available after the app emits the ready event.
Direct main process connection check
If you need to check the connection status in the main process, you can use net.isOnline() directly instead of communicating from the renderer process via IPC.
Never use npx for running tools
Do not use npx because it is considered dangerous as it can silently fetch and execute arbitrary packages from the registry. Instead, either spawn the executable directly from node_modules/.bin/<tool> (or the platform equivalent on Windows), or invoke via yarn <tool> or yarn run <tool>, which resolves to the locally installed version without the registry fallback that npx performs.
Electron core directory structure
The Electron repository contains: shell/ with Core C++ application code (browser/, renderer/, common/, app/, services/ subdirectories), lib/ with TypeScript/JavaScript library code (browser/, renderer/, common/ subdirectories), patches/ for upstream dependency patches (chromium/, node/, and others), spec/ with 1189+ TypeScript test files, docs/ for API documentation, build/ for build configuration, script/ for build and automation scripts, and chromium_src/ for Chromium source overrides. The parent directory contains Chromium source.
Build tools setup with @electron/build-tools
Electron uses @electron/build-tools for development. Install globally with: npm i -g @electron/build-tools. The 'e' command is the primary CLI. Configuration files are located at ~/.electron_build_tools/configs/
Essential e command for configuration management
Configuration management commands: e init <name> --root=<path> --bootstrap testing creates new build config and syncs, e use <name> switches to a different build configuration, e show current displays active configuration name, e show configs lists all available configurations.
Essential e command for build and development
Build and development commands: e sync fetches/updates all source code and applies patches, e sync --3 syncs with 3-way merge (required for Chromium upgrades), e build builds Electron (runs GN + Ninja), e build -k 999 builds and continues on errors (up to 999), e build -t <target> builds specific target (e.g., electron:node_headers), e start runs the built Electron executable, e start --version verifies Electron launches and prints version, e test runs the test suite, e debug runs Electron in debugger (lldb on macOS, gdb on Linux).
Patch management commands
Patch management: e patches <target> exports patches for a target (chromium, node, v8, etc.), e patches all exports all patches from all targets, e patches --list-targets lists available patch targets.
Typical Electron development workflow
Typical workflow: (1) Ensure correct config with e show current, (2) Sync code with e sync, (3) Make changes in shell/ or lib/ or parent Chromium directory, (4) Build with e build, (5) Test changes with e start and e test, (6) If modified patched files in Chromium: cd to Chromium repo, git add files, git commit with description, cd back to electron, run e patches chromium to export the patch.
Patches system workflow
Patches are stored in patches/{target}/*.patch and applied via e sync --3 to target repo commits. The reverse flow (e patches) exports target repo commits back to patch files. Patch configuration in patches/config.json maps patch directories to target repos.
Patch creation and modification rules
When working with patches: fix existing patches 99% of the time rather than creating new ones, preserve original authorship in TODO comments, never change TODO assignees (TODO(name) must retain original name), each patch file includes commit message explaining its purpose. To create/modify patches: make changes in the target repo (e.g., ../ for Chromium), create a git commit, run e patches <target> to export.
Fixing patch conflicts using CI artifact
When fixing a patch conflict on a branch with an open PR, check the PR's failed Apply Patches CI run for an update-patches.patch artifact before running e sync locally. CI has already performed the 3-way merge and exported the resolved patch diff. Use: gh run list --repo electron/electron --branch <pr-branch> --workflow "Apply Patches" --limit 1, then get artifact ID with gh api repos/electron/electron/actions/runs/<run-id>/artifacts, then fetch with gh api repos/electron/electron/actions/artifacts/<artifact-id>/zip, then git am update-patches.patch and git push. If no artifact exists, fall back to e sync --3 and resolve manually.
Test suite location and commands
Tests are located in spec/ directory. Run full test suite with: e test. Test frameworks used are Mocha, Chai, and Sinon.
Build configuration structure
GN build arguments are located in build/args/: testing.gn for debug/testing builds, release.gn for release builds, all.gn for common arguments for all builds. Main build file is BUILD.gn. Feature flags are in buildflags/buildflags.gni.
PR body requirements with Notes section
Pull request 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.
PR semver labels
When creating PRs with write access to electron/electron, add one semver label: semver/none for build changes, refactors, CI, or anything with no end-user impact; semver/patch for backwards-compatible bug fixes; semver/minor for backwards-compatible new functionality; semver/major for incompatible API changes.
PR backport target labels policy
Add target/{N}-x-y labels for each supported release branch a change should land on. Default policy: Bug fixes — backport to all active release lines except the oldest; Security fixes — backport to all active release lines including the oldest; Features (semver/minor) and breaking changes (semver/major) — no backport labels, main-only by default. Find active release branches by checking label colors — active target/* labels use color #ad244f, older/EOL ones use #ededed. Command: gh label list --repo electron/electron --search target/ --json name,color --jq '.[] | select(.color == "ad244f") | .name'
Code style enforcement
C++ follows Chromium style, enforced by clang-format. TypeScript/JavaScript follows oxlint configuration in .oxlintrc.json. Run linters with: npm run lint for all linters, npm run lint:js for oxlint over all JS/TS/MJS sources, npm run lint:clang-format for C++ formatting, npm run lint:api-history to validate API history YAML blocks in docs.
Key files in Electron repository
Key files: BUILD.gn is the main GN build configuration, DEPS contains dependency versions and checkout paths, patches/config.json contains patch target configuration, filenames.gni contains source file lists by platform, package.json contains Node.js dependencies and scripts.
Environment variables for Electron development
GN_EXTRA_ARGS is for additional GN arguments (useful in CI). ELECTRON_RUN_AS_NODE=1 runs Electron as Node.js.
Useful Git commands for Chromium work
To find CL that changed a file: cd .. (Chromium repo), git log --oneline -10 -- {file}, git blame -L {start},{end} -- {file}. To look for Chromium CL reference in commit: git log -1 {commit_sha} and find "Reviewed-on:" line. To find which patch affects a file: grep -l "filename.cc" patches/chromium/*.patch.
CI/CD workflows
GitHub Actions workflows are in .github/workflows/: build.yml is main build workflow, pipeline-electron-lint.yml is linting, pipeline-segment-electron-test.yml is testing, audit-branch-ci.yml provides table of release-branch CI runs that errored, archaeologist-dig.yml provides electron.d.ts diff report. Workflows upload findings as build artifact named audit-results.md (unarchived as raw markdown). Agents should list run artifacts with GET /repos/electron/electron/actions/runs/{run_id}/artifacts, find audit-results.md, and fetch its archive_download_url.
Resolving patch conflicts during sync
If encountering patch conflicts during sync: use e sync --3 for 3-way merge, check if file was renamed/moved upstream, verify patch is still needed. If build error in patched file: find the patch with grep -l "filename" patches/chromium/*.patch, match existing patch style (#if 0 guards, BUILDFLAG conditionals, etc.). For remote build issues: try e build --no-remote to build locally, check reclient/siso configuration in build config.