Node.js como sidecar

En esta guía vamos a empaquetar una aplicación Node.js en un binario autónomo para ser utilizado como Sidecar en una aplicación Tauri sin requerir que el usuario final tenga una instalación de Node.js. Este tutorial de ejemplo es aplicable únicamente a sistemas operativos de escritorio.

Recomendamos leer primero la guía general de sidecars para comprender mejor cómo funcionan los sidecars de Tauri.

Objetivos

• Empaquetar una aplicación Node.js como un binario.
• Integrar este binario como un Sidecar de Tauri.

Detalles de Implementación

• Para esto usamos la herramienta pkg, pero cualquier otra herramienta que pueda compilar JavaScript o TypeScript en una aplicación binaria funcionará.
• También puedes incrustar el propio entorno de ejecución de Node en tu aplicación Tauri y distribuir el JavaScript empaquetado como un recurso, pero esto distribuirá el contenido JavaScript como archivos medianamente legibles y el runtime suele ser más grande que una aplicación empaquetada con pkg.

En este ejemplo crearemos una aplicación Node.js que lee la entrada desde la línea de comandos process.argv y escribe la salida en stdout usando console.log.
Puedes aprovechar sistemas alternativos de comunicación entre procesos como un servidor localhost, stdin/stdout o sockets locales. Ten en cuenta que cada uno tiene sus propias ventajas, inconvenientes y consideraciones de seguridad.

Requisitos previos

Una aplicación Tauri existente configurada con el plugin shell, que compile y se ejecute localmente en tu equipo.

Crear una aplicación de laboratorio

Si no eres un usuario avanzado, es muy recomendable que utilices las opciones y frameworks proporcionados aquí. Es solo un laboratorio, puedes eliminar el proyecto cuando hayas terminado.

Bash

sh <(curl https://create.tauri.app/sh)

PowerShell

irm https://create.tauri.app/ps | iex

Fish

sh (curl -sSL https://create.tauri.app/sh | psub)

npm

npm create tauri-app@latest

Yarn

yarn create tauri-app

pnpm

pnpm create tauri-app

deno

deno run -A npm:create-tauri-app

bun

bun create tauri-app

Cargo

cargo install create-tauri-app --locked
cargo create-tauri-app

• Nombre del proyecto: node-sidecar-lab
• Elige qué lenguaje usar para tu frontend: TypeScript / JavaScript
• Elige tu gestor de paquetes: pnpm
• Elige tu plantilla de UI: Vanilla
• Elige tu variante de UI: TypeScript

Nota

Por favor, sigue primero la guía del plugin shell para configurar e inicializar el plugin correctamente. Sin que el plugin esté inicializado y configurado, el ejemplo no funcionará.

Guía

1. Inicializar el Proyecto del Sidecar

   Creemos un nuevo proyecto Node.js para contener la implementación de nuestro sidecar. Crea un nuevo directorio en la carpeta raíz de tu aplicación Tauri (en este ejemplo lo llamaremos sidecar-app) y ejecuta el comando init de tu gestor de paquetes de Node.js preferido dentro del directorio:

   npm

   npm init

   yarn

   yarn init

   pnpm

   pnpm init

   Compilaremos nuestra aplicación Node.js en un binario autónomo usando pkg entre otras opciones. Instalémoslo como una dependencia de desarrollo dentro del nuevo sidecar-app:

   npm

   npm add @yao-pkg/pkg --save-dev

   yarn

   yarn add @yao-pkg/pkg --dev

   pnpm

   pnpm add @yao-pkg/pkg --save-dev

2. Escribir la Lógica del Sidecar

   Ahora podemos comenzar a escribir código JavaScript que será ejecutado por nuestra aplicación Tauri.

   En este ejemplo procesaremos un comando desde los argumentos de la línea de comandos y escribiremos la salida en stdout, lo que significa que nuestro proceso será de corta duración y solo manejará un comando a la vez. Si tu aplicación debe ser de larga duración, considera utilizar sistemas alternativos de comunicación entre procesos.

   Creemos un archivo index.js en nuestro directorio sidecar-app y escribamos una aplicación Node.js básica:

   sidecar-app/index.js

   const command = process.argv[2];
   
   switch (command) {
     case 'hello':
       const message = process.argv[3];
       console.log(`Hello ${message}!`);
       break;
     default:
       console.error(`unknown command ${command}`);
       process.exit(1);
   }

3. Empaquetar el Sidecar

   Para empaquetar nuestra aplicación Node.js en un binario autónomo, crea un script en el archivo package.json:

   sidecar-app/package.json

   {
     "scripts": {
       "build": "pkg index.ts --output my-sidecar"
     }
   }

   npm

   npm run build

   yarn

   yarn build

   pnpm

   pnpm build

   Esto creará el binario sidecar-app/my-sidecar en Linux y macOS, y un ejecutable sidecar-app/my-sidecar.exe en Windows.

   Para las aplicaciones sidecar, debemos asegurarnos de que el binario tenga el patrón de nombre correcto; para obtener más información, lee Incrustar Binarios Externos. Para renombrar este archivo al nombre de archivo esperado para el sidecar de Tauri y también moverlo a nuestro proyecto Tauri, podemos usar el siguiente script de Node.js como ejemplo inicial:

   sidecar-app/rename.js

   import { execSync } from 'child_process';
   import fs from 'fs';
   
   const ext = process.platform === 'win32' ? '.exe' : '';
   
   const targetTriple = execSync('rustc --print host-tuple').toString().trim();
   if (!targetTriple) {
     console.error('Failed to determine platform target triple');
   }
   // TODO: create `src-tauri/binaries` dir
   fs.renameSync(
     `my-sidecar${ext}`,
     `../src-tauri/binaries/my-sidecar-${targetTriple}${ext}`
   );

   Nota

   El indicador --print host-tuple se añadió en Rust 1.84.0. Si estás usando una versión anterior, tendrás que analizar la salida de rustc -Vv en su lugar:

   const rustInfo = execSync('rustc -vV');
   const targetTriple = /host: (\S+)/g.exec(rustInfo)[1];

   Y ejecuta node rename.js desde el directorio sidecar-app.

   En este paso, el directorio /src-tauri/binaries debería contener el binario del sidecar renombrado.

4. Configurar el permiso del plugin-shell

   Después de instalar el plugin shell, asegúrate de configurar los permisos requeridos.

   Ten en cuenta que usamos "args": true, pero opcionalmente puedes proporcionar un array ["hello"], leer más.

   src-tauri/capabilities/default.json

   {
     "permissions": [
       "core:default",
       "opener:default",
       {
         "identifier": "shell:allow-execute",
         "allow": [
           {
             "args": true,
             "name": "binaries/my-sidecar",
             "sidecar": true
           }
         ]
       }
     ]
   }

5. Configurar el Sidecar en la Aplicación Tauri

   Ahora que tenemos nuestra aplicación Node.js lista, podemos conectarla a nuestra aplicación Tauri configurando el array bundle > externalBin:

   src-tauri/tauri.conf.json

   {
     "bundle": {
       "externalBin": ["binaries/my-sidecar"]
     }
   }

   La CLI de Tauri se encargará de empaquetar el binario del sidecar siempre que exista como src-tauri/binaries/my-sidecar-<target-triple>.

6. Ejecutar el Sidecar

   Podemos ejecutar el binario sidecar ya sea desde código Rust o directamente desde JavaScript.

   JavaScript

   Ejecutemos el comando hello en el sidecar de Node.js directamente:

   import { Command } from '@tauri-apps/plugin-shell';
   
   const message = 'Tauri';
   
   const command = Command.sidecar('binaries/my-sidecar', ['hello', message]);
   const output = await command.execute();
   // once everything is configured it should log "Hello Tauri" in the browser console.
   console.log(output.stdout)

   Rust

   Redirijamos un comando de Tauri hello hacia el sidecar de Node.js:

   use tauri_plugin_shell::ShellExt;
   
   #[tauri::command]
   async fn hello(app: tauri::AppHandle, cmd: String, message: String) -> String {
       let sidecar_command = app
           .shell()
           .sidecar("my-sidecar")
           .unwrap()
           .arg(cmd)
           .arg(message);
       let output = sidecar_command.output().await.unwrap();
       String::from_utf8(output.stdout).unwrap()
   }

   Regístralo en invoke_handler y llámalo en el frontend con:

   import { invoke } from "@tauri-apps/api/core";
   
   const message = "Tauri"
   console.log(await invoke("hello", { cmd: 'hello', message }))

7. Ejecución

   Vamos a probarlo

   npm

   npm run tauri dev

   yarn

   yarn tauri dev

   pnpm

   pnpm tauri dev

   deno

   deno task tauri dev

   bun

   bun tauri dev

   cargo

   cargo tauri dev

   Abre las DevTools con F12 (o Cmd+Option+I en macOS) y deberías ver la salida del comando del sidecar.

   Si encuentras algún problema, por favor abre un issue en GitHub.