#53145: docs: explain process.defaultApp and open-url timing for deep links
Merged
Created: Aug 24, 2026, 9:00:22 AM
Merged: Aug 26, 2026, 11:08:19 AM
2 comments
Target: main
Description of Change
The deep links tutorial shows the process.defaultApp branch around app.setAsDefaultProtocolClient and a synchronous open-url listener on macOS, but never explains why either is written the way it is. Cold-start argv handling on Windows/Linux was already documented in #49142; this fills in the two remaining gaps from #40173:
- Why
process.defaultAppmatters: in dev (electron .), the OS launches the generic Electron executable, so the protocol has to be registered with an explicitexecPathand script path or there'd be no way to know which app to load. - Why
open-urlmust be registered synchronously on macOS:Browser::OpenURL(shell/browser/browser.cc) notifies observers immediately with no queueing, so a listener attached after anawaitcan miss a cold-start deep link entirely.
Fixes #40173
Checklist
- I have built and tested this change
- I have filled out the PR description
- I have reviewed and verified the changes
-
npm testpasses - tests are changed or added
- relevant API documentation, tutorials, and examples are updated and follow the documentation style guide
- PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense
Release Notes
Notes: none
Backports
Semver Impact
Major
Breaking changes
Minor
New features
Patch
Bug fixes
None
Docs, tests, etc.
Semantic Versioning helps users understand the impact of updates:
- Major (X.y.z): Breaking changes that may require code modifications
- Minor (x.Y.z): New features that maintain backward compatibility
- Patch (x.y.Z): Bug fixes that don't change the API
- None: Changes that don't affect using facing parts of Electron