feat: add Node.js as a sidecar guide (tauri-apps#2771)

Co-authored-by: Tillmann <[email protected]>

Author: lucasfernog

src/content/docs/develop/sidecar.mdx

@@ -9,16 +9,17 @@ You may need to embed external binaries to add additional functionality to your
 
 Binaries are executables written in any programming language. Common use cases are Python CLI applications or API servers bundled using `pyinstaller`.
 
-To bundle the binaries of your choice, you can add the `externalBin` property to the `tauri > bundle` object in your `tauri.conf.json`. `externalBin` expects a list of strings targeting binaries either with absolute or relative paths.
+To bundle the binaries of your choice, you can add the `externalBin` property to the `tauri > bundle` object in your `tauri.conf.json`.
+The `externalBin` configuration expects a list of strings targeting binaries either with absolute or relative paths.
 
-Here is a sample to illustrate the configuration. This is not a complete `tauri.conf.json` file:
+Here is a Tauri configuration snippet to illustrate a sidecar configuration:
 
 ```json title="src-tauri/tauri.conf.json"
 {
   "bundle": {
     "externalBin": [
       "/absolute/path/to/sidecar",
-      "relative/path/to/binary",
+      "../relative/path/to/binary",
       "binaries/my-sidecar"
     ]
   }
@@ -27,13 +28,19 @@ Here is a sample to illustrate the configuration. This is not a complete `tauri.
 
 :::note
 
-The relative paths are relative to the `tauri.conf.json` file which is in the `src-tauri` directory. So `binaries/my-sidecar` would represent `<PROJECT ROOT>/src-tauri/binaries/my-sidecar`.
+The relative paths are relative to the `tauri.conf.json` file which is in the `src-tauri` directory.
+So `binaries/my-sidecar` would represent `<PROJECT ROOT>/src-tauri/binaries/my-sidecar`.
 
 :::
 
-To make the external binary work on each supported architecture, a binary with the same name and a `-$TARGET_TRIPLE` suffix must exist on the specified path. For instance, `"externalBin": ["binaries/my-sidecar"]` requires a `src-tauri/binaries/my-sidecar-x86_64-unknown-linux-gnu` executable on Linux or `src-tauri/binaries/my-sidecar-aarch64-apple-darwin` on Mac OS with Apple Silicon.
+To make the external binary work on each supported architecture, a binary with the same name and a `-$TARGET_TRIPLE` suffix must exist on the specified path.
+For instance, `"externalBin": ["binaries/my-sidecar"]` requires a `src-tauri/binaries/my-sidecar-x86_64-unknown-linux-gnu` executable on Linux or `src-tauri/binaries/my-sidecar-aarch64-apple-darwin` on Mac OS with Apple Silicon.
 
-You can find your **current** platform's `-$TARGET_TRIPLE` suffix by looking at the `host:` property reported by the `rustc -Vv` command.
+You can find your **current** platform's `-$TARGET_TRIPLE` suffix by looking at the `host:` property reported by the following command:
+
+```sh
+rustc -Vv
+```
 
 If the `grep` and `cut` commands are available, as they should on most Unix systems, you can extract the target triple directly with the following command:
 
@@ -50,37 +57,29 @@ rustc -Vv | Select-String "host:" | ForEach-Object {$_.Line.split(" ")[1]}
 Here's a Node.js script to append the target triple to a binary:
 
 ```javascript
-const execa = require('execa');
-const fs = require('fs');
+import { execSync } from 'child_process';
+import fs from 'fs';
 
-let extension = '';
-if (process.platform === 'win32') {
-  extension = '.exe';
-}
+const ext = process.platform === 'win32' ? '.exe' : '';
 
-async function main() {
-  const rustInfo = (await execa('rustc', ['-vV'])).stdout;
-  const targetTriple = /host: (\S+)/g.exec(rustInfo)[1];
-  if (!targetTriple) {
-    console.error('Failed to determine platform target triple');
-  }
-  fs.renameSync(
-    `src-tauri/binaries/sidecar${extension}`,
-    `src-tauri/binaries/sidecar-${targetTriple}${extension}`
-  );
+const rustInfo = execSync('rustc -vV');
+const targetTriple = /host: (\S+)/g.exec(rustInfo)[1];
+if (!targetTriple) {
+  console.error('Failed to determine platform target triple');
 }
-
-main().catch((e) => {
-  throw e;
-});
+fs.renameSync(
+  `src-tauri/binaries/sidecar${extension}`,
+  `src-tauri/binaries/sidecar-${targetTriple}${extension}`
+);
 ```
 
-Note that this script will not work if you compile for a different architecture than the one its running on.
+Note that this script will not work if you compile for a different architecture than the one its running on,
+so only use it as a starting point for your own build scripts.
 
 ## Running it from Rust
 
 :::note
-Please follow the shell [plugin guide](/plugin/shell/) first to set up and initialize the plugin correctly.
+Please follow the [shell plugin guide](/plugin/shell/) first to set up and initialize the plugin correctly.
 Without the plugin being initialized and configured the example won't work.
 :::
 
@@ -90,7 +89,6 @@ On the Rust side, import the `tauri_plugin_shell::ShellExt` trait and call the `
 use tauri_plugin_shell::ShellExt;
 use tauri_plugin_shell::process::CommandEvent;
 
-// `sidecar()` expects just the filename, NOT the whole path like in JavaScript
 let sidecar_command = app.shell().sidecar("my-sidecar").unwrap();
 let (mut rx, mut _child) = sidecar_command
   .spawn()
@@ -99,7 +97,8 @@ let (mut rx, mut _child) = sidecar_command
 tauri::async_runtime::spawn(async move {
   // read events such as stdout
   while let Some(event) = rx.recv().await {
-    if let CommandEvent::Stdout(line) = event {
+    if let CommandEvent::Stdout(line_bytes) = event {
+      let line = String::from_utf8_lossy(&line_bytes);
       window
         .emit("message", Some(format!("'{}'", line)))
         .expect("failed to emit event");
@@ -110,6 +109,24 @@ tauri::async_runtime::spawn(async move {
 });
 ```
 
+:::note
+The `sidecar()` function expects just the filename, NOT the whole path configured in the `externalBin` array.
+
+Given the following configuration:
+
+```json title="src-tauri/tauri.conf.json"
+{
+  "bundle": {
+    "externalBin": ["binaries/app", "my-sidecar", "../scripts/sidecar"]
+  }
+}
+```
+
+The appropriate way to execute the sidecar is by calling `app.shell().sidecar(name)` where `name` is either `"app"`, `"my-sidecar"` or `"sidecar"`
+instead of `"binaries/app"` for instance.
+
+:::
+
 You can place this code inside a Tauri command to easily pass the AppHandle or you can store a reference to the AppHandle in the builder script to access it elsewhere in your application.
 
 ## Running it from JavaScript
@@ -118,14 +135,17 @@ In the JavaScript code, import the `Command` class from the `@tauri-apps/plugin-
 
 ```javascript
 import { Command } from '@tauri-apps/plugin-shell';
-// `binaries/my-sidecar` is the EXACT value specified on `tauri.conf.json > tauri > bundle > externalBin`
-const sidecar_command = Command.sidecar('binaries/my-sidecar');
-const output = await sidecar_command.execute();
+const command = Command.sidecar('binaries/my-sidecar');
+const output = await command.execute();
 ```
 
+:::note
+The string provided to `Command.sidecar` must match one of the strings defined in the `externalBin` configuration array.
+:::
+
 ## Passing arguments
 
-You can pass arguments to Sidecar commands just like you would for running normal `Command`s.
+You can pass arguments to Sidecar commands just like you would for running normal [Command][std::process::Command].
 
 Arguments can be either **static** (e.g. `-o` or `serve`) or **dynamic** (e.g. `<file_path>` or `localhost:<PORT>`). You define the arguments in the exact order in which you'd call them. Static arguments are defined as-is, while dynamic arguments can be defined using a regular expression.
 
@@ -157,7 +177,6 @@ First, define the arguments that need to be passed to the sidecar command in `sr
               "validator": "\\S+"
             }
           ],
-          "cmd": "",
           "name": "binaries/my-sidecar",
           "sidecar": true
         }
@@ -180,7 +199,8 @@ In Rust:
 use tauri_plugin_shell::ShellExt;
 #[tauri::command]
 async fn call_my_sidecar(app: tauri::AppHandle) {
-  let sidecar_command = app.shell()
+  let sidecar_command = app
+    .shell()
     .sidecar("my-sidecar")
     .unwrap()
     .args(["arg1", "-a", "--arg2", "any-string-that-matches-the-validator"]);
@@ -192,7 +212,6 @@ In JavaScript:
 
 ```javascript
 import { Command } from '@tauri-apps/plugin-shell';
-// `binaries/my-sidecar` is the EXACT value specified on `tauri.conf.json > tauri > bundle > externalBin`
 // notice that the args array matches EXACTLY what is specified on `tauri.conf.json`.
 const command = Command.sidecar('binaries/my-sidecar', [
   'arg1',
@@ -202,3 +221,5 @@ const command = Command.sidecar('binaries/my-sidecar', [
 ]);
 const output = await command.execute();
 ```
+
+[std::process::Command]: https://doc.rust-lang.org/std/process/struct.Command.html

src/content/docs/learn/sidecar-nodejs.mdx

@@ -2,11 +2,186 @@
 title: Node.js as a sidecar
 sidebar:
   order: 1
-  badge:
-    text: Stub
-    variant: caution
 ---
 
-import Stub from '@components/Stub.astro';
+import CommandTabs from '@components/CommandTabs.astro';
+import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
+import CTA from '@fragments/cta.mdx';
 
-<Stub />
+In this guide we are going to package a Node.js application to a self contained binary
+to be used as a sidecar in a Tauri application without requiring the end user to have a Node.js installation.
+This example tutorial is applicable for desktop operating systems only.
+
+We recommend reading the general [sidecar guide] first for a deeper understanding of how Tauri sidecars work.
+
+In this example we will create a Node.js application that reads input from the command line [process.argv]
+and writes output to stdout using [console.log]. <br/>
+You can leverage alternative inter-process communication systems such as a localhost server, stdin/stdout or local sockets.
+Note that each has their own advantages, drawbacks and security concerns.
+
+## Prerequisites
+
+An existing Tauri application set up with the shell plugin, that compiles and runs for you locally.
+
+:::tip[Create a lab app]
+
+If you are not an advanced user it's **highly recommended** that you use the options and frameworks provided here. It's just a lab, you can delete the project when you're done.
+
+<CTA />
+
+- Project name: `node-sidecar-lab`
+- Choose which language to use for your frontend: `Typescript / Javascript`
+- Choose your package manager: `pnpm`
+- Choose your UI template: `Vanilla`
+- Choose your UI flavor: `Typescript`
+- Would you like to setup the project for mobile as well? `yes`
+
+:::
+
+:::note
+Please follow the [shell plugin guide](/plugin/shell/) first to set up and initialize the plugin correctly.
+Without the plugin being initialized and configured the example won't work.
+:::
+
+## Guide
+
+<Steps>
+
+1.  ##### Initialize Sidecar Project
+
+    Let's create a new Node.js project to contain our sidecar implementation.
+    Create a new directory **in your Tauri application root folder** (in this example we will call it `sidecar-app`)
+    and run the `init` command of your preferred Node.js package manager inside the directory:
+
+    <CommandTabs npm="npm init" yarn="yarn init" pnpm="pnpm init" />
+
+    We will compile our Node.js application to a self container binary using [pkg].
+    Let's install it as a development dependency:
+
+    <CommandTabs
+      npm="npm add pkg --save-dev"
+      yarn="yarn add pkg --dev"
+      pnpm="pnpm add pkg --save-dev"
+    />
+
+1.  ##### Write Sidecar Logic
+
+    Now we can start writing JavaScript code that will be executed by our Tauri application.
+
+    In this example we will process a command from the command line argmuents and write output to stdout,
+    which means our process will be short lived and only handle a single command at a time.
+    If your application must be long lived, consider using alternative inter-process communication systems.
+
+    Let's create a `index.js` file in our `sidecar-app` directory and write a basic Node.js app:
+
+    ```js title=sidecar-app/index.js
+    const command = process.argv[2];
+
+    switch (command) {
+      case 'ping':
+        const message = process.argv[3];
+        console.log(`pong, ${message}`);
+        break;
+      default:
+        console.error(`unknown command ${command}`);
+        process.exit(1);
+    }
+    ```
+
+1.  ##### Package the Sidecar
+
+    To package our Node.js application to a self contained binary, we can run the following `pkg` command:
+
+    <CommandTabs
+      npm="npm run pkg -- --output app"
+      yarn="yarn pkg --output app"
+      pnpm="pnpm pkg --output app"
+    />
+
+    This will create the `sidecar-app/app` binary on Linux and macOS, and a `sidecar-app/app.exe` executable on Windows.
+    To rename this file to the expected Tauri sidecar filename, we can use the following Node.js script:
+
+    ```js
+    import { execSync } from 'child_process';
+    import fs from 'fs';
+
+    const ext = process.platform === 'win32' ? '.exe' : '';
+
+    const rustInfo = execSync('rustc -vV');
+    const targetTriple = /host: (\S+)/g.exec(rustInfo)[1];
+    if (!targetTriple) {
+      console.error('Failed to determine platform target triple');
+    }
+    fs.renameSync(
+      `app${ext}`,
+      `../src-tauri/binaries/app-${targetTriple}${ext}`
+    );
+    ```
+
+1.  ##### Configure the Sidecar in the Tauri Application
+
+    Now that we have our Node.js application ready, we can connect it to our Tauri application
+    by configuring the [`bundle > externalBin`] array:
+
+    ```json title="src-tauri/tauri.conf.json"
+    {
+      "bundle": {
+        "externalBin": ["binaries/app"]
+      }
+    }
+    ```
+
+    The Tauri CLI will handle the bundling of the sidecar binary as long as it exists as `src-tauri/binaries/app-<target-triple>`.
+
+1.  ##### Execute the Sidecar
+
+    We can run the sidecar binary either from Rust code or directly from JavaScript.
+
+    <Tabs>
+
+      <TabItem label="JavaScript">
+
+        Let's execute the `ping` command in the Node.js sidecar directly:
+
+        ```javascript
+        import { Command } from '@tauri-apps/plugin-shell';
+
+        const message = 'Tauri';
+
+        const command = Command.sidecar('binaries/app', ['ping', message]);
+        const output = await command.execute();
+        const response = output.stdout;
+        ```
+
+      </TabItem>
+
+      <TabItem label="Rust">
+
+        Let's pipe a `ping` Tauri command to the Node.js sidecar:
+
+        ```rust
+        #[tauri::command]
+        async fn ping(app: tauri::AppHandle, message: String) -> String {
+          let sidecar_command = app
+            .shell()
+            .sidecar("app")
+            .unwrap()
+            .arg("ping")
+            .arg(message);
+          let output = sidecar_command.output().unwrap();
+          let response = String::from_utf8(output.stdout).unwrap();
+          response
+        }
+        ```
+
+      </TabItem>
+
+    </Tabs>
+
+</Steps>
+
+[sidecar guide]: /develop/sidecar
+[process.argv]: https://nodejs.org/docs/latest/api/process.html#processargv
+[console.log]: https://nodejs.org/api/console.html#consolelogdata-args
+[pkg]: https://github.com/vercel/pkg
+[`bundle > externalBin`]: /reference/config/#externalbin