protocols.md

Custom URL Protocols

app.protocol registers/deregisters OS-level handlers for custom URL schemes (e.g. myapp://...), backed by protocol-registry.

register

app.protocol.register("myapp", `"${process.execPath}" "$_URL_"`, {
  override: true,
  appName: "My App",
});

• scheme - protocol name, without :// (e.g. "myapp").
• command - the command to run when a myapp://... link is opened. $_URL_ is replaced with the launched URL.
• options.override - overwrite an existing handler for this protocol.
• options.terminal - run the command inside a terminal window.
• options.appName - display name for the registered handler.

deregister / isRegistered / getDefaultApp

await app.protocol.deregister("myapp");
const exists = await app.protocol.isRegistered("myapp");
const current = await app.protocol.getDefaultApp("myapp");

Handling the launch URL

When the OS opens a myapp://... link, your app is launched (or focused, if singleInstance is enabled) with the URL in process.argv. Combine with single instance to receive the URL in an already-running instance via the buntop:second-instance event:

window.addEventListener("buntop:second-instance", (e) => {
  const url = e.detail.argv.find((a) => a.startsWith("myapp://"));
  if (url) handleLaunchUrl(url);
});