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)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.