Flutter Alone
A Flutter plugin to prevent duplicate desktop app instances (Windows & macOS)
Overview
Flutter Alone is a Flutter plugin that prevents duplicate instances of desktop applications. When a user tries to launch an app that's already running, it blocks the new instance and automatically focuses the existing window. It uses platform-native mechanisms — global Mutex on Windows and lockfiles on macOS.
Key Features
- Single Instance Guarantee: Leverages native mechanisms for each platform — Mutex on Windows, Lockfile on macOS
- Automatic Window Focus: Restores and brings the original window to the foreground when a duplicate launch is detected, even if minimized or hidden
- Multi-language Alert Messages: Built-in English and Korean support with custom message configuration
- Flexible Configuration: Multiple strategies including direct mutex naming and package ID-based auto-generation
- Debug Mode Handling: Skips duplicate checks during development to avoid interfering with hot reload workflows
- System Tray Compatibility: Properly detects and restores apps hidden in the system tray
Supported Platforms
| Windows | macOS | Linux |
|---|---|---|
| ✅ | ✅ | 🚧 |
Technical Highlights
- Platform-native Implementation: Windows uses a C API-based plugin (
FlutterAlonePluginCApi) while macOS uses a Swift-based plugin (FlutterAlonePlugin), each calling native OS APIs directly. - Separated Configuration Objects: Concerns are split across
MutexConfig,MacOSConfig,MessageConfig, and more, allowing flexible composition. - Lockfile Path Management: On macOS, lockfile paths are managed using the native temporary directory API, eliminating the
path_providerdependency. - Multi-user Account Support: Detects instances running under different user accounts on the same machine.
Why It Stands Out
Preventing duplicate instances is a common requirement for desktop apps, yet few packages in the Flutter ecosystem address it comprehensively. Flutter Alone goes beyond simple blocking — it handles window restoration, system tray compatibility, multi-language messages, and debug mode exceptions, covering the details that matter in production. It also provides a compatibility guide for popular packages like window_manager, making it ready for real-world deployment.