Debugging Your App

A comprehensive guide to debugging ToDesktop applications during development and in production.

# Overview

ToDesktop apps have two processes you may need to debug:

• Renderer process — Your web app running in Chromium. Debug this like you would a web app, using Chrome DevTools.
• Main process — The Node.js process that manages windows, native features, and system integration. Debug this using Node.js debugging tools.

# Debugging the Renderer Process

The renderer process is where your web app runs. You can debug it using Chrome DevTools, just like debugging a website.

# Opening DevTools

There are several default ways to open DevTools in your ToDesktop app if DevTools are enabled in your application config:

1. Via the View menu — Click View → Toggle Developer Tools
2. Via keyboard shortcut — Use Cmd+Option+I (macOS) or Ctrl+Shift+I (Windows/Linux)
3. Programmatically — Call webContents.toggleDevTools() from your code

        import { webContents } from '@todesktop/client-core';

webContents.toggleDevTools();

      

Once open, you have access to the full Chrome DevTools suite: Console, Elements, Network, Sources, and more.

# Renderer Process Logs

Console logs from your web app (e.g., console.log()) appear in the DevTools Console tab. These are not written to disk by default.

# Debugging the Main Process

The main process handles native functionality, window management, and system integration. Debugging it requires connecting a Node.js debugger.

# During Local Development

When running your app locally via ToDesktop Builder, you can use the "Show in Finder" option to locate the executable:

Then run it from the terminal with the --inspect flag:

        # macOS - navigate to the app's MacOS folder
cd "/path/to/Your App.app/Contents/MacOS"
./Your\ App --inspect=5858

      

# Debugging an Installed App

For apps installed on a user's machine (or your own machine for testing), you can attach a debugger the same way:

macOS:

        cd /Applications/Your\ App.app/Contents/MacOS
./Your\ App --inspect=5858

      

Windows:

        cd "C:\Users\YourName\AppData\Local\Programs\Your App"
"Your App.exe" --inspect=5858

      

Linux:

        cd /opt/your-app
./your-app --inspect=5858

      

# Connecting Chrome DevTools to the Main Process

Once your app is running with --inspect=5858:

1. Open Google Chrome and navigate to chrome://inspect/#devices
2. Click Configure and add localhost:5858 to the target discovery settings
3. Enable port forwarding
4. Your app should appear under "Remote Target" — click Inspect

This gives you a full DevTools window connected to the main process, where you can set breakpoints, inspect variables, and step through code.

# Log File Locations

ToDesktop writes main process logs to disk. These are invaluable for debugging issues in production.

# Main Process Logs

Reading logs from the terminal:

        # macOS
cat ~/Library/Logs/Your\ App/main.log

# Windows (PowerShell)
Get-Content "$env:USERPROFILE\AppData\Roaming\Your App\logs\main.log"

# Linux
cat ~/.config/Your\ App/logs/main.log

      

Tailing logs in real-time:

        # macOS / Linux
tail -f ~/Library/Logs/Your\ App/main.log

# Windows (PowerShell)
Get-Content "$env:USERPROFILE\AppData\Roaming\Your App\logs\main.log" -Wait

      

# Renderer Process Logs

Renderer process logs (console.log(), etc.) are only visible in DevTools and are not written to disk by default.

# Simulating Auto-Updates

Testing auto-update behaviour normally requires publishing a release, which is slow and cumbersome. ToDesktop Builder lets you simulate auto-update events locally.

# Enabling Simulation Mode

1. In ToDesktop Builder, click the vertical ellipsis (⋮) next to the Run button
2. Select Simulate auto-update events locally
3. Run your app

This triggers a simulated update sequence when the app starts:

1. checking-for-update
2. update-available
3. download-progress
4. update-downloaded

If you restart the app via the update prompt (or programmatically), you'll get the update-not-available sequence, simulating a post-update launch.

# Listening to Update Events

You can listen to these events to test your update UI:

        import { todesktopUpdater } from '@todesktop/client-core';

todesktopUpdater.on('checking-for-update', () => {
  console.log('Checking for update...');
});

todesktopUpdater.on('update-available', () => {
  console.log('Update available!');
});

todesktopUpdater.on('download-progress', (progress) => {
  console.log(`Download progress: ${progress.percent}%`);
});

todesktopUpdater.on('update-downloaded', () => {
  console.log('Update downloaded, ready to install');
});

      

See Configuring Auto-Updates for more details.

# Debugging Tips

• Add version logging — Log your app version on startup so you know which version generated a log file
• Use structured logging — Include timestamps and log levels to make logs easier to parse
• Test on all platforms — Issues often appear on only one platform
• Keep DevTools enabled during development — If you want to disabled it then disable only for production releases. Often it's best to keep it enabled even for production builds though.

# Related Documentation

• Using Chrome Developer Tools
• Accessing Application Logs
• Configuring Auto-Updates
• Using VMs for Testing