Deep linking (window.Electron.onDeepLink)
Handles the OS routing a custom-URL-scheme link (myapp://...) back to your running or cold-starting app. Source: src/main/deep-link.ts. Not an IPC-channel bridge like most modules — it's driven by native OS events (open-url on macOS, argv/second-instance on Windows/Linux). Opt-in: set app.deepLinkingScheme in electron.config.ts (e.g. 'myapp' enables myapp:// links) — see App configuration. Disabled by default; setupDeepLinking() is only called when a scheme is configured.
Method
| Method | Returns | Notes |
|---|---|---|
onDeepLink(callback: (data: { url: string }) => void) |
() => void (unsubscribe) |
Fires whenever the OS routes a <scheme>://... URL to the app. Not part of .safe (event subscription, never throws). |
Cold-start vs already-running
macOS and Windows/Linux signal a running app differently, and this module hides that difference from you:
- macOS — the OS re-activates the existing process and fires Electron's
open-urlevent. - Windows/Linux — launching via a link starts a new process, which immediately hands its
argvto the original process via Electron'ssecond-instanceevent, then exits.
If a link arrives before a window exists yet (cold start, still launching), it's held in memory rather than dropped, and delivered via onDeepLink() the moment the main window is ready — flushDeepLink() runs this check right after window creation. The URL the app was launched with (if any) is also kept available afterward, in case app-level routing logic needs to ask "what did we cold-start with?" once the UI has actually mounted, rather than only reacting to the one onDeepLink() event.
Every incoming URL is validated against the configured scheme and capped at 8192 characters before being forwarded — malformed or wrong-scheme URLs are silently dropped rather than delivered.
Example
const unsubscribe = window.Electron.onDeepLink(({ url }) => {
const path = new URL(url).pathname; // e.g. 'myapp://reset-password/abc123' → '/reset-password/abc123'
router.navigate(path);
});
See Protocols for checking/registering the app as the OS's default handler for the scheme at runtime, and Troubleshooting for common deep-link pitfalls.
.safe
None — onDeepLink is a pure event subscription and has no .safe counterpart.