debug-tauri

Tauri WebView Debugger

Automated debugging workflow for Tauri applications using tauri-plugin-debug-tools with official plugin integration.

Prerequisites

• tauri-plugin-debug-tools installed and registered
• tauri-plugin-log (v2.0+): Official logging plugin for automatic console collection
• tauri-plugin-screenshots (v2.0+): Cross-platform screenshot capture
• Debug permissions enabled: debug-tools:default, log:default, screenshots:default
• Frontend logger initialized via attachConsole() (recommended for automatic log forwarding)

Quick Start

Run TAURI_APP_NAME=<app-binary-name> scripts/capture.sh to verify process and capture screenshot.

If process not found, start your dev server (e.g., tauri dev) and retry.

Debug Workflow

Copy this checklist to track progress:

Debug Progress:
- [ ] Step 1: Verify process status
- [ ] Step 2: Capture screenshot
- [ ] Step 3: Collect console logs
- [ ] Step 4: Capture WebView state
- [ ] Step 5: Analyze findings
- [ ] Step 6: Generate debug report
- [ ] Step 7: Propose fixes

Step 1: Verify Process Status

Run: TAURI_APP_NAME=<your-app> scripts/capture.sh

This checks if the app is running and captures an initial screenshot.

Step 2: Capture Screenshot

Via Plugin API (Recommended):

import { captureMainWindow } from "tauri-plugin-debug-tools/screenshotHelper";
const imagePath = await captureMainWindow();

Legacy: capture.sh script (macOS screencapture). See SCREENSHOTS.md for details.

Step 3: Collect Console Logs

Console Logger (Frontend - Recommended):

The consoleLogger automatically collects frontend logs and errors in a ring buffer and flushes them to a temp file.

// Import at app entry point to initialize automatic collection
import "tauri-plugin-debug-tools/consoleLogger";

// Use debugTools for explicit logging
import { debugTools } from "tauri-plugin-debug-tools/consoleLogger";
debugTools.log("App started");
debugTools.error("Something went wrong");

Finding consoleLogger Log Files:

import { invoke } from '@tauri-apps/api/core';

// Get actual log file path
const logPath = await invoke('plugin:debug-tools|reset_debug_logs');
console.log('Console logs stored at:', logPath);

Platform-specific consoleLogger locations:

• macOS: /tmp/tauri_console_logs_[app_name]_[pid].jsonl
• Linux: /tmp/tauri_console_logs_[app_name]_[pid].jsonl
• Windows: %TEMP%\tauri_console_logs_[app_name]_[pid].jsonl

Where [app_name] is the application name and [pid] is the process ID.

Backend Logs (tauri-plugin-log):

import { logger } from "tauri-plugin-debug-tools/logAdapter";

// Initialize once at app startup
const detach = await logger.initialize();

// Logs auto-forwarded to platform-specific location
logger.info("App started");
logger.error("Something went wrong");

Backend log locations:

• macOS: ~/Library/Logs/{bundle_id}/debug.log
• Linux: ~/.local/share/{bundle_id}/logs/debug.log
• Windows: {LOCALAPPDATA}\{bundle_id}\logs\debug.log

Alternative: Use debugBridge API. See IPC_COMMANDS.md for all methods.

Step 4: Capture WebView State

import { captureWebViewState } from "tauri-plugin-debug-tools/debugBridge";
const state = await captureWebViewState();

Returns: { url, title, user_agent, viewport }

Step 5: Analyze Findings

• Visual: Check screenshot for UI issues, errors, layout problems
• Logs: Review errors, warnings, patterns
• State: Verify URL, viewport, user agent
• Performance: Check for memory leaks, high CPU usage

Step 6: Generate Debug Report

Use template in REPORT_TEMPLATE.md.

Step 7: Propose Fixes

Based on collected evidence:

• Identify root cause
• Suggest specific code changes
• Provide implementation steps

References

IPC Commands: IPC_COMMANDS.md - Console logs, WebView state, debug commands Screenshots: SCREENSHOTS.md - Capture methods and troubleshooting Troubleshooting: TROUBLESHOOTING.md - Common errors and solutions Report Template: REPORT_TEMPLATE.md - Structured debug report format

Legacy reference: REFERENCE.md contains combined documentation (will be deprecated)