# How Fluxer Handles Multi-Instance Scenarios and Prevents Multiple App Launches

> Learn how Fluxer prevents multiple app launches using requestSingleInstanceLock to manage multi-instance scenarios and gracefully handle duplicate processes for a seamless user experience.

- Repository: [Fluxer/fluxer](https://github.com/fluxerapp/fluxer)
- Tags: internals
- Published: 2026-03-17

---

**Fluxer uses Electron's `requestSingleInstanceLock()` API to acquire an OS-level mutex at startup, immediately quitting duplicate processes while the primary instance listens for `second-instance` events to handle subsequent launch attempts.**

Fluxer is an Electron-based desktop application that ensures only one process runs at any given time using a robust single-instance lock pattern. According to the `fluxerapp/fluxer` source code, the implementation prevents multiple app launches while enabling the running instance to receive command-line arguments and deep-link URLs from subsequent attempts.

## The Core Single-Instance Lock Mechanism

Fluxer's entry point implements a three-stage locking strategy that guarantees singleton behavior across all platforms.

### Requesting the Lock on Startup

In [`fluxer_desktop/src/main/index.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/index.tsx), the application attempts to acquire a single-instance lock immediately upon startup using Electron's built-in API:

```typescript
const gotTheLock = app.requestSingleInstanceLock();   // line 81

```

This method creates a mutex at the operating system level. When the first instance launches, `gotTheLock` evaluates to `true`, granting exclusive ownership. Any subsequent launches receive `false` and trigger immediate termination.

### Exiting Duplicate Processes

If the lock cannot be obtained, the process exits cleanly without creating any windows or registering handlers:

```typescript
if (!gotTheLock) {
    app.quit();                                    // lines 84-85
}

```

This ensures that only one main process remains active, preventing resource conflicts and window duplication.

## Handling Second-Instance Events

When a user attempts to launch Fluxer while it is already running, the primary instance receives a `second-instance` event instead of spawning a new process. The main entry point wires this handler immediately after securing the lock:

```typescript
app.on('second-instance', (_event, argv, _workingDirectory) => {
    handleSecondInstance(argv);                    // lines 86-88
});

```

The `argv` parameter contains the command-line arguments from the duplicate launch attempt, allowing Fluxer to process deep links or file associations even when triggered from a second instance.

## Deep Link Processing in the Primary Instance

The actual handling of secondary launch arguments resides in [`fluxer_desktop/src/main/DeepLinks.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/DeepLinks.tsx). The `handleSecondInstance` function receives the argument array and coordinates the response:

```typescript
// src/main/DeepLinks.tsx
export function handleSecondInstance(argv: string[]) {
    // Focus the main window and process deep-link URLs or file paths
}

```

This architecture ensures that URLs opened via protocol handlers or files dragged onto the application icon are routed to the existing window rather than being lost when the duplicate process quits.

## Key Implementation Files

The single-instance guarantee spans several modules in the `fluxer_desktop` package:

- **[`fluxer_desktop/src/main/index.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/index.tsx)** – Main entry point that acquires the single-instance lock and registers the `second-instance` event listener.
- **[`fluxer_desktop/src/main/DeepLinks.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/DeepLinks.tsx)** – Exports `handleSecondInstance()` to process command-line arguments and deep-link URLs forwarded from duplicate launches.
- **[`fluxer_desktop/src/main/Window.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/Window.tsx)** – Manages window focus and visibility operations called by the second-instance handler.
- **[`fluxer_desktop/src/main/IpcHandlers.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/IpcHandlers.tsx)** – Registers IPC channels that rely on the singleton instance assumption.

## Reusable Implementation Pattern

You can adapt Fluxer's approach for any Electron application using this minimal implementation:

```typescript
import { app } from 'electron';

const gotTheLock = app.requestSingleInstanceLock();

if (!gotTheLock) {
  app.quit();
} else {
  app.on('second-instance', (_event, argv) => {
    console.log('Second launch with arguments:', argv);
    // Bring window to front or process deep links here
  });

  app.whenReady().then(() => {
    // Initialize main window and menus
  });
}

```

## Summary

Fluxer prevents multiple concurrent launches by implementing an OS-level single-instance lock:

- **Requests a mutex at startup** using `app.requestSingleInstanceLock()` in [`index.tsx`](https://github.com/fluxerapp/fluxer/blob/main/index.tsx).
- **Terminates duplicate processes immediately** if the lock is unavailable.
- **Forwards launch arguments** to the primary instance via the `second-instance` event and `handleSecondInstance()` handler.
- **Processes deep links** in the running instance without spawning additional windows.

## Frequently Asked Questions

### How does Fluxer prevent multiple windows from opening?

Fluxer calls `app.requestSingleInstanceLock()` at startup in [`fluxer_desktop/src/main/index.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/index.tsx). If another instance is running, `gotTheLock` returns `false` and the new process executes `app.quit()` before creating any windows, ensuring only one GUI instance exists.

### What happens to command-line arguments when launching Fluxer twice?

When a second launch occurs, the primary instance receives a `second-instance` event containing the new command-line arguments. The `handleSecondInstance(argv)` function in [`DeepLinks.tsx`](https://github.com/fluxerapp/fluxer/blob/main/DeepLinks.tsx) processes these arguments, enabling the running app to open files or URLs passed by the duplicate attempt.

### Is the single-instance lock OS-specific?

No. Electron's `requestSingleInstanceLock()` creates a cross-platform mutex that works on Windows, macOS, and Linux. The implementation in [`fluxer_desktop/src/main/index.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/index.tsx) uses this standard Electron API, making the behavior consistent across all supported operating systems.

### Where is the single-instance logic implemented in Fluxer?

The core logic resides in [`fluxer_desktop/src/main/index.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/index.tsx) at lines 81-88, where the lock is requested and the `second-instance` handler is registered. Supporting functionality for argument processing lives in [`fluxer_desktop/src/main/DeepLinks.tsx`](https://github.com/fluxerapp/fluxer/blob/main/fluxer_desktop/src/main/DeepLinks.tsx).