사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/dchuk/claude-code-tauri-skills --skill embedding-tauri-sidecars시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Tauri Sidecars: Embedding External Binaries
This skill covers embedding and executing external binaries (sidecars) in Tauri applications, including configuration, cross-platform considerations, and execution from Rust and JavaScript.
Overview
Sidecars are external binaries embedded within Tauri applications to extend functionality or eliminate the need for users to install dependencies. They can be executables written in any programming language.
Common Use Cases:
- Python CLI applications packaged with PyInstaller
- Go or Rust compiled binaries for specific tasks
- Node.js applications bundled as executables
- API servers or background services
Plugin Dependency
Sidecars require the shell plugin:
Cargo.toml:
[dependencies]
tauri-plugin-shell = "2"Register in main.rs:
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_shell::init())
.run(tauri::generate_context!())
.expect("error while running tauri application");
}Frontend package:
npm install @tauri-apps/plugin-shellConfiguration
Registering Sidecars
Configure sidecars in tauri.conf.json under bundle.externalBin. Paths are relative to src-tauri:
{
"bundle": {
"externalBin": [
"binaries/my-sidecar",
"../external/processor"
]
}
}Important: The path is a stem. Tauri appends the target triple suffix at build time.
Cross-Platform Binary Naming
Each sidecar requires platform-specific variants with target triple suffixes:
| Platform | Architecture | Required Filename |
|---|---|---|
| Linux | x86_64 | my-sidecar-x86_64-unknown-linux-gnu |
| Linux | ARM64 | my-sidecar-aarch64-unknown-linux-gnu |
| macOS | Intel | my-sidecar-x86_64-apple-darwin |
| macOS | Apple Silicon | my-sidecar-aarch64-apple-darwin |
| Windows | x86_64 | my-sidecar-x86_64-pc-windows-msvc.exe |
Determine your target triple:
rustc --print host-tuple # Rust 1.84.0+
rustc -Vv | grep host # Older versionsDirectory Structure
src-tauri/
binaries/
my-sidecar-x86_64-unknown-linux-gnu
my-sidecar-aarch64-apple-darwin
my-sidecar-x86_64-apple-darwin
my-sidecar-x86_64-pc-windows-msvc.exe
tauri.conf.json
src/main.rsExecuting Sidecars from Rust
Basic Execution
use tauri_plugin_shell::ShellExt;
#[tauri::command]
async fn run_sidecar(app: tauri::AppHandle) -> Result<String, String> {
let output = app
.shell()
.sidecar("my-sidecar")
.map_err(|e| e.to_string())?
.output()
.await
.map_err(|e| e.to_string())?;
if output.status.success() {
Ok(String::from_utf8_lossy(&output.stdout).to_string())
} else {
Err(String::from_utf8_lossy(&output.stderr).to_string())
}
}Note: Pass only the filename to sidecar(), not the full path from configuration.
With Arguments
#[tauri::command]
async fn process_file(app: tauri::AppHandle, file_path: String) -> Result<String, String> {
let output = app
.shell()
.sidecar("processor")
.map_err(|e| e.to_string())?
.args(["--input", &file_path, "--format", "json"])
.output()
.await
.map_err(|e| e.to_string())?;
Ok(String::from_utf8_lossy(&output.stdout).to_string())
}Spawning Long-Running Processes
For sidecars that run continuously (API servers, watchers):
use tauri_plugin_shell::{ShellExt, process::CommandEvent};
#[tauri::command]
async fn start_server(app: tauri::AppHandle) -> Result<u32, String> {
let (mut rx, child) = app
.shell()
.sidecar("api-server")
.map_err(|e| e.to_string())?
.args(["--port", "8080"])
.spawn()
.map_err(|e| e.to_string())?;
let pid = child.pid();
tauri::async_runtime::spawn(async move {
while let Some(event) = rx.recv().await {
match event {
CommandEvent::Stdout(line) => println!("{}", String::from_utf8_lossy(&line)),
CommandEvent::Stderr(line) => eprintln!("{}", String::from_utf8_lossy(&line)),
CommandEvent::Terminated(payload) => {
println!("Terminated: {:?}", payload.code);
break;
}
_ => {}
}
}
});
Ok(pid)
}Managing Sidecar Lifecycle
use std::sync::Mutex;
use tauri::State;
use tauri_plugin_shell::{ShellExt, process::CommandChild};
struct SidecarState {
child: Mutex<Option<CommandChild>>,
}
#[tauri::command]
async fn start_sidecar(app: tauri::AppHandle, state: State<'_, SidecarState>) -> Result<(), String> {
let (_, child) = app.shell().sidecar("service").map_err(|e| e.to_string())?
.spawn().map_err(|e| e.to_string())?;
*state.child.lock().unwrap() = Some(child);
Ok(())
}
#[tauri::command]
async fn stop_sidecar(state: State<'_, SidecarState>) -> Result<(), String> {
if let Some(child) = state.child.lock().unwrap().take() {
child.kill().map_err(|e| e.to_string())?;
}
Ok(())
}Executing Sidecars from JavaScript
Permission Configuration
Grant shell execution permissions in src-tauri/capabilities/default.json:
{
"$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default",
"windows": ["main"],
"permissions": [
"core:default",
{
"identifier": "shell:allow-execute",
"allow": [{ "name": "binaries/my-sidecar", "sidecar": true }]
}
]
}Basic Execution
import { Command } from '@tauri-apps/plugin-shell';
async function runSidecar(): Promise<string> {
const command = Command.sidecar('binaries/my-sidecar');
const output = await command.execute();
if (output.code === 0) return output.stdout;
throw new Error(output.stderr);
}With Arguments
async function processFile(filePath: string): Promise<string> {
const command = Command.sidecar('binaries/processor', [
'--input', filePath, '--format', 'json'
]);
const output = await command.execute();
return output.stdout;
}Handling Streaming Output
import { Command, Child } from '@tauri-apps/plugin-shell';
async function runWithStreaming(): Promise<Child> {
const command = Command.sidecar('binaries/long-task');
command.on('close', (data) => console.log(`Finished: ${data.code}`));
command.on('error', (error) => console.error(error));
command.stdout.on('data', (line) => console.log(line));
command.stderr.on('data', (line) => console.error(line));
return await command.spawn();
}Managing Long-Running Processes
let serverProcess: Child | null = null;
async function startServer(): Promise<number> {
const command = Command.sidecar('binaries/api-server', ['--port', '8080']);
command.stdout.on('data', console.log);
serverProcess = await command.spawn();
return serverProcess.pid;
}
async function stopServer(): Promise<void> {
if (serverProcess) {
await serverProcess.kill();
serverProcess = null;
}
}Argument Validation
Configure argument validation in capabilities:
{
"identifier": "shell:allow-execute",
"allow": [{
"name": "binaries/my-sidecar",
"sidecar": true,
"args": [
"-o",
"--verbose",
{ "validator": "\\S+" }
]
}]
}Argument types:
- Static string: Exact match required (
-o,--verbose) - Validator object: Regex pattern for dynamic values
- `true`: Allow any argument (use with caution)
Cross-Platform Considerations
Building Platform-Specific Binaries
Rust sidecars:
cargo build --release --target x86_64-unknown-linux-gnu
cp target/x86_64-unknown-linux-gnu/release/my-tool \
src-tauri/binaries/my-tool-x86_64-unknown-linux-gnuPython with PyInstaller:
pyinstaller --onefile my_script.py
mv dist/my_script dist/my_script-x86_64-unknown-linux-gnuPlatform Notes
Windows:
- Executables must have
.exeextension - Handle line endings in text file processing
macOS:
- Use
lipofor universal binaries (Intel + Apple Silicon) - Code signing may be required for distribution
- Gatekeeper may block unsigned sidecars
Linux:
- Mark binaries as executable (
chmod +x) - Consider glibc version compatibility
- Static linking reduces dependency issues
Complete Example
tauri.conf.json:
{
"productName": "My App",
"version": "1.0.0",
"identifier": "com.example.myapp",
"bundle": {
"externalBin": ["binaries/data-processor"]
}
}capabilities/default.json:
{
"$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default",
"windows": ["main"],
"permissions": [
"core:default",
{
"identifier": "shell:allow-execute",
"allow": [{
"name": "binaries/data-processor",
"sidecar": true,
"args": [
"--input", { "validator": "^[a-zA-Z0-9_\\-./]+$" },
"--output", { "validator": "^[a-zA-Z0-9_\\-./]+$" }
]
}]
}
]
}src/main.rs:
use tauri_plugin_shell::ShellExt;
#[tauri::command]
async fn process_data(app: tauri::AppHandle, input: String, output: String) -> Result<String, String> {
let result = app.shell().sidecar("data-processor").map_err(|e| e.to_string())?
.args(["--input", &input, "--output", &output])
.output().await.map_err(|e| e.to_string())?;
if result.status.success() {
Ok(String::from_utf8_lossy(&result.stdout).to_string())
} else {
Err(String::from_utf8_lossy(&result.stderr).to_string())
}
}
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_shell::init())
.invoke_handler(tauri::generate_handler![process_data])
.run(tauri::generate_context!())
.expect("error while running tauri application");
}Frontend (App.tsx):
import { invoke } from '@tauri-apps/api/core';
function App() {
const handleProcess = async () => {
try {
const result = await invoke('process_data', {
input: '/path/to/input.txt',
output: '/path/to/output.txt'
});
console.log('Result:', result);
} catch (error) {
console.error('Error:', error);
}
};
return <button onClick={handleProcess}>Process Data</button>;
}Best Practices
- Validate all sidecar paths: Never pass untrusted paths to sidecars
- Use argument validators: Restrict allowed arguments in capabilities
- Handle errors gracefully: Sidecars may fail or be missing
- Clean up processes: Kill spawned processes on app exit
- Test on all platforms: Binary naming and execution varies
- Consider binary size: Sidecars increase bundle size significantly