Debugging Guide - Trezor Suite

Effective debugging is essential for maintaining and developing Trezor Suite. This guide covers debugging techniques for web, desktop, and native applications.

Development Tools

Chrome DevTools

Built-in browser debugging tools

React DevTools

React component inspection

Redux DevTools

Redux state debugging

VS Code Debugger

IDE-integrated debugging

Web Application Debugging

Chrome DevTools

Start development server

yarn suite:dev

Access at http://localhost:8000

Open DevTools

Press F12 or Cmd+Option+I (Mac) / Ctrl+Shift+I (Windows/Linux)
Or right-click → “Inspect”

Use debugging features

Console: Log messages and errors
Sources: Set breakpoints in code
Network: Monitor API requests
Elements: Inspect DOM and styles

Source Maps

Source maps are enabled in development mode for easy debugging.

In DevTools Sources tab:

Navigate to webpack:// folder
Find your source file (e.g., packages/suite/src/...)
Set breakpoints by clicking line numbers
Refresh page or trigger action to hit breakpoint

Console Debugging

Basic logging
Conditional logging
Performance timing

console.log('Variable value:', myVariable);
console.error('Error occurred:', error);
console.warn('Warning message');
console.table(arrayOfObjects); // Nice table format

if (process.env.NODE_ENV === 'development') {
    console.log('Debug info:', data);
}

// Or use a debug flag
const DEBUG = true;
if (DEBUG) console.log('Debug:', state);

console.time('operation');
// ... code to measure
console.timeEnd('operation'); // Logs elapsed time

Remove console.log statements before committing. Use a proper logging library for production.

Desktop Application Debugging

Electron Main Process

The main process runs Node.js code for the Electron app.

Enable debugging

Modify packages/suite-desktop/package.json:

"dev:run": "electron --inspect=5858 ."

Open Chrome inspector

Open Chrome and navigate to chrome://inspect
Click “Configure” in “Devices” tab
Ensure “Discover network targets” is enabled
Add localhost:5858
Your Electron app should appear in the list

Start debugging

yarn suite:dev:desktop

Click “inspect” under your app in Chrome inspector

Source: Electron Debugging Documentation

Electron Renderer Process

The renderer process runs the web UI:

Built-in DevTools
Remote debugging

In the Electron app window:

Cmd+Option+I (Mac) or Ctrl+Shift+I (Windows/Linux)
Same as Chrome DevTools

Access renderer DevTools in Chrome:

Start app with remote debugging enabled
Open chrome://inspect in Chrome
Find renderer process and click “inspect”

Production Build Debugging

Debug production builds with logging:

Linux
macOS
Windows
NixOS

./Trezor-Suite-22.7.2.AppImage --log-level=debug

./Trezor\ Suite.app/Contents/MacOS/Trezor\ Suite --log-level=debug

"C:\Users\[user-name]\AppData\Local\Programs\Trezor Suite\Trezor Suite.exe" --log-level=debug

appimage-run ./Trezor-Suite.AppImage --log-level=debug

Logs are written to the console and log files in the app data directory.

React Debugging

React DevTools

Install the React DevTools extension:

Component tree
Profiler
Hooks

Inspect component hierarchy
View component props and state
Find component in tree by selecting element
Navigate to component source

React Error Boundaries

Use error boundaries to catch and debug React errors gracefully.

import { Component, ErrorInfo, ReactNode } from 'react';

interface ErrorBoundaryProps {
    children: ReactNode;
}

interface ErrorBoundaryState {
    hasError: boolean;
    error?: Error;
}

class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
    constructor(props: ErrorBoundaryProps) {
        super(props);
        this.state = { hasError: false };
    }

    static getDerivedStateFromError(error: Error): ErrorBoundaryState {
        return { hasError: true, error };
    }

    componentDidCatch(error: Error, errorInfo: ErrorInfo) {
        console.error('Error boundary caught:', error, errorInfo);
        // Log to error reporting service
    }

    render() {
        if (this.state.hasError) {
            return <div>Something went wrong. {this.state.error?.message}</div>;
        }

        return this.props.children;
    }
}

Redux Debugging

Redux DevTools

Install Redux DevTools Extension:

View actions

See all dispatched actions in real-time
Inspect action type and payload
Jump to action in timeline

State inspection

View complete Redux state tree
See state changes after each action
Diff state between actions

Time travel

Replay actions
Skip actions to see alternative states
Undo/redo actions

Export/import state

Export state for bug reports
Import state to reproduce issues
Share state with team

Logging Redux Actions

Action logger
Selector debugging

import { Middleware } from '@reduxjs/toolkit';

const actionLogger: Middleware = store => next => action => {
    console.group(action.type);
    console.log('Action:', action);
    console.log('Previous State:', store.getState());
    
    const result = next(action);
    
    console.log('Next State:', store.getState());
    console.groupEnd();
    
    return result;
};

// Add to store configuration (development only)

import { createSelector } from '@reduxjs/toolkit';

const selectUser = createSelector(
    [(state: RootState) => state.user],
    user => {
        console.log('selectUser called with:', user);
        return user;
    },
);

Network Debugging

Chrome Network Tab

Monitor requests

View all network requests
See request/response headers
Inspect payload data
Check response status codes

Filter requests

Filter by type (XHR, Fetch, WS)
Search by URL or domain
Show only failed requests

Throttling

Simulate slow network
Test loading states
Debug timeout issues

Trezor Connect Debugging

Trezor Connect handles device communication.

import TrezorConnect from '@trezor/connect';

// Enable debug mode
TrezorConnect.init({
    manifest: { /* ... */ },
    debug: true, // Logs all communication
});

// Listen to events
TrezorConnect.on('DEVICE_EVENT', event => {
    console.log('Device event:', event);
});

TrezorConnect.on('UI_EVENT', event => {
    console.log('UI event:', event);
});

Performance Debugging

React Profiler

Record profile
Analyze results

Open React DevTools
Switch to “Profiler” tab
Click record button
Perform actions in app
Stop recording

Performance API

// Measure component render time
const MyComponent = () => {
    React.useEffect(() => {
        performance.mark('component-render-start');
        
        return () => {
            performance.mark('component-render-end');
            performance.measure(
                'component-render',
                'component-render-start',
                'component-render-end',
            );
            
            const measure = performance.getEntriesByName('component-render')[0];
            console.log('Render time:', measure.duration, 'ms');
        };
    });

    return <div>Content</div>;
};

Chrome Performance Tab

Record performance

Open Chrome DevTools → Performance tab
Click record button
Perform slow action
Stop recording

Analyze profile

Flame chart: See what’s taking time
Bottom-Up: Longest running functions
Call Tree: Function call hierarchy
Event Log: Timeline of events

VS Code Debugging

Launch Configuration

Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Chrome Debug",
            "type": "chrome",
            "request": "launch",
            "url": "http://localhost:8000",
            "webRoot": "${workspaceFolder}/packages/suite",
            "sourceMapPathOverrides": {
                "webpack:///*": "${webRoot}/*"
            }
        },
        {
            "name": "Jest Debug",
            "type": "node",
            "request": "launch",
            "program": "${workspaceFolder}/node_modules/.bin/jest",
            "args": ["--runInBand", "--coverage=0"],
            "console": "integratedTerminal"
        }
    ]
}

Set breakpoints

Click to the left of line numbers in VS Code

Start debugging

Press F5 or use Debug panel

Use debug controls

Continue (F5)
Step over (F10)
Step into (F11)
Step out (Shift+F11)

Common Debugging Scenarios

Component not rendering

Check React DevTools component tree
Verify component is in render path
Check conditional rendering logic
Inspect parent component props
Look for errors in console

State not updating

Open Redux DevTools
Check if action was dispatched
Verify action payload is correct
Inspect reducer logic
Check if component is subscribed to state

Slow performance

Use React Profiler to find slow components
Check for unnecessary re-renders
Verify memoization (useMemo, useCallback)
Look for expensive computations
Use Chrome Performance tab for details

API request failing

Open Network tab in DevTools
Find the failing request
Check request headers and payload
Inspect response status and body
Verify CORS settings if applicable
Check Trezor Connect logs for device communication

Development on Windows

Windows development requires special setup. See the Environment Setup guide.

Common Windows Issues

Always use Git Bash, not CMD or PowerShell, for running commands.

Slow builds: Exclude trezor-suite folder from Windows Defender
Path issues: Use forward slashes in paths
Line endings: Configure Git to use LF: git config --global core.autocrlf input
Node version: Use Node.js >=25.4.0 (not the version in .nvmrc)

Debugging Best Practices

Reproduce consistently

Find reliable steps to reproduce the issue before debugging

Isolate the problem

Narrow down which component, function, or module has the issue

Check the obvious first

Console errors
Network failures
Missing data
Type errors

Use debugger effectively

Set breakpoints at suspected locations
Inspect variable values
Step through code execution

Document findings

Note what you learned for future reference or bug reports

Resources

Chrome DevTools

Official Chrome DevTools documentation

React DevTools

React debugging tools guide

Redux DevTools

Redux debugging extension

Electron Debugging

Electron debugging guide

Setup

Contributing

Packages

​Development Tools

Chrome DevTools

React DevTools

Redux DevTools

VS Code Debugger

​Web Application Debugging

​Chrome DevTools

​Source Maps

​Console Debugging

​Desktop Application Debugging

​Electron Main Process

​Electron Renderer Process

​Production Build Debugging

​React Debugging

​React DevTools

​React Error Boundaries

​Redux Debugging

​Redux DevTools

​Logging Redux Actions

​Network Debugging

​Chrome Network Tab

​Trezor Connect Debugging

​Performance Debugging

​React Profiler

​Performance API

​Chrome Performance Tab

​VS Code Debugging

​Launch Configuration

​Common Debugging Scenarios

​Development on Windows

​Common Windows Issues

​Debugging Best Practices

​Resources

Chrome DevTools

React DevTools

Redux DevTools

Electron Debugging

Build docs developers (and LLMs) love

Development Tools

Web Application Debugging

Chrome DevTools

Source Maps

Console Debugging

Desktop Application Debugging

Electron Main Process

Electron Renderer Process

Production Build Debugging

React Debugging

React DevTools

React Error Boundaries

Redux Debugging

Redux DevTools

Logging Redux Actions

Network Debugging

Chrome Network Tab

Trezor Connect Debugging

Performance Debugging

React Profiler

Performance API

Chrome Performance Tab

VS Code Debugging

Launch Configuration

Common Debugging Scenarios

Development on Windows

Common Windows Issues

Debugging Best Practices

Resources