docs(features): Add single instance page (#1931)

* Add Installation and Usage * Add Focusing WIndow example * update example description * Add more info about usage Co-authored-by: Lucas Fernandes Nogueira <[email protected]> * Improve Focusing new instance description Co-authored-by: Lucas Fernandes Nogueira <[email protected]> * Remove unnecessary LOC from examples * add parameter name * Change `main.rs` to `lib.rs` * Update Setup and usage * Use Starlight Steps * Improve wording for Usage Section * Update focusing new instance line * Update src/content/docs/features/single-instance.mdx Co-authored-by: Vitor Ayres <[email protected]> * Apply recommendations * Make description more uniform --------- Co-authored-by: Lucas Fernandes Nogueira <[email protected]> Co-authored-by: Vitor Ayres <[email protected]>
tauri-apps · Apr 1, 2024 · 903b5a5 · 903b5a5
1 parent b2c7c00
commit 903b5a5
Showing 1 changed file with 105 additions and 6 deletions.
diff --git a/src/content/docs/features/single-instance.mdx b/src/content/docs/features/single-instance.mdx
@@ -1,14 +1,113 @@
 ---
 title: Single Instance
-description: Ensure a single instance of your tauri app is running.
+description: Ensure that a single instance of your Tauri app is running at a time.
 ---
 
-import Stub from '@components/Stub.astro';
 import PluginLinks from '@components/PluginLinks.astro';
+import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
+import CommandTabs from '@components/CommandTabs.astro';
 
 <PluginLinks plugin="single-instance" showJsLinks={false} />
 
-<Stub>
-	Based on
-	https://github.com/tauri-apps/plugins-workspace/tree/v2/plugins/single-instance
-</Stub>
+Ensure that a single instance of your tauri app is running at a time using the Single Instance Plugin.
+
+## Setup
+
+Install the Single Instance plugin to get started.
+
+<Tabs>
+    <TabItem label="Automatic">
+
+    Use your project's package manager to add the dependency:
+
+    <CommandTabs npm="npm run tauri add single-instance"
+    yarn="yarn run tauri add single-instance"
+    pnpm="pnpm tauri add single-instance"
+    cargo="cargo tauri add single-instance" />
+
+    </TabItem>
+    <TabItem label="Manual">
+    <Steps> 
+    <ol>
+      <li> 
+        **Install :** Add the plugin to the project's dependencies in `Cargo.toml`.
+      <Tabs>
+        <TabItem label="crates.io">
+      ```toml title="src-tauri/Cargo.toml" ins={2}
+      [dependencies]
+      tauri-plugin-single-instance = "2.0.0-beta"
+      ```
+        </TabItem>
+        <TabItem label="Git">
+
+      ```toml title="src-tauri/Cargo.toml" ins={2}
+      [dependencies]
+      tauri-plugin-single-instance = { git = "https://github.com/tauri-apps/plugins-workspace", branch = "v2" }
+      ```
+        </TabItem>
+      </Tabs>
+      </li>
+      <li>
+        **Initialize :** Update `lib.rs` (or `main.rs` for desktop-only apps) to initialize the plugin:
+
+      ```rust title="src-tauri/src/lib.rs" ins={3}
+      pub fn run() {
+          tauri::Builder::default()
+              .plugin(tauri_plugin_single_instance::init(|app, args, cwd| {}))
+              .run(tauri::generate_context!())
+              .expect("error while running tauri application");
+      }
+      ```
+      </li>
+    </ol>
+    </Steps>
+    </TabItem>
+
+</Tabs>
+
+## Usage
+
+The plugin is already installed and initialized, and it should be functioning correctly right away. Nevertheless, we can also enhance its functionality with the `init()` method.
+
+The plugin `init()` method takes a closure that is invoked when a new app instance was started, but closed by the plugin. 
+The closure has three arguments: 
+1. **`app` :** The [AppHandle](https://docs.rs/tauri/latest/tauri/struct.AppHandle.html) of the application.
+2. **`args` :** The list of arguments, that was passed by the user to initiate this new instance.
+3. **`cwd` :** The Current Working Directory denotes the directory from which the new application instance was launched.
+
+So, the closure should look like below
+
+```rust
+.plugin(tauri_plugin_single_instance::init(|app, args, cwd| {
+  // Write your code here...
+}))
+```
+
+### Focusing on New Instance
+
+By default, when you initiate a new instance while the application is already running, no action is taken. To focus the window of the running instance when user tries to open a new instance, alter the callback closure as follows:
+
+
+```rust title="src-tauri/src/lib.rs" {1} {5-7} {12-21}
+use tauri::{AppHandle, Manager};
+
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_single_instance::init(|app, args, cwd| {
+            let _ = show_window(app);
+        }))
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+
+fn show_window(app: &AppHandle) {
+    let windows = app.webview_windows();
+
+    windows
+        .values()
+        .next()
+        .expect("Sorry, no window found")
+        .set_focus()
+        .expect("Can't Bring Window to Focus");
+}
+```