single-instance.md

Single Instance

By default, multiple copies of your app can run side by side. Enable singleInstance to ensure only one runs at a time per app + channel:

const app = new BunTop({
  title: "My App",
  singleInstance: true,
});

Behavior

• The first instance to start becomes the "primary" instance and runs normally.
• If a second instance is launched while the primary is running:
  • the primary instance's window is focused (window.focus()),
  • the primary instance receives a buntop:second-instance event on the frontend with { argv }, where argv is the new process's process.argv.slice(2) (useful for things like file associations or myapp:// protocol launches),
  • the second instance exits immediately without creating a window.

window.addEventListener("buntop:second-instance", (e) => {
  console.log("relaunched with args:", e.detail.argv);
});

Scope

The single-instance lock is keyed by identifier + channel (same scoping as app.paths.userData()), so dev/beta/release builds (or different apps) don't interfere with each other.