santichausis

#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.defaultApp matters: in dev (electron .), the OS launches the generic Electron executable, so the protocol has to be registered with an explicit execPath and script path or there'd be no way to know which app to load.
  • Why open-url must be registered synchronously on macOS: Browser::OpenURL (shell/browser/browser.cc) notifies observers immediately with no queueing, so a listener attached after an await can 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 test passes
  • 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

44-x-y
Merged
PR Number
#53210
Merged At
Aug 26, 2026, 12:05:09 PM
Released In
Not yet
Release Date
Not yet

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