Skip to main content

​
Prerequisites

Before running any application, ensure you’ve completed:
  1. Environment setup
  2. Dependency installation (yarn)
  3. Essential libraries build (yarn build:essential)
Running apps without building essential libraries first will result in errors.

​
Trezor Suite Web

The web version of Trezor Suite runs in your browser.

​
Development Server

yarn suite:dev
Features:
  • Runs on http://localhost:8000
  • Hot module replacement (HMR)
  • React DevTools integration
  • Source maps enabled
  • Fast refresh on file changes
Initial compilation takes 2-3 minutes. Subsequent updates are nearly instant with HMR.

​
Experimental: Vite Development

EXPERIMENTAL - For development only. Use yarn suite:dev for production-like experience.
yarn suite:dev:vite
Benefits:
  • Instant server start
  • Extremely fast HMR
  • Better development experience
Limitations:
  • May not match production behavior
  • Not all features may work correctly

​
Production Preview

Test the production build locally: 
yarn suite:build:web:preview
Features:
  • Production-optimized code
  • Security headers applied
  • Identical to production environment
  • Served on localhost

​
Trezor Suite Desktop

The Electron-based desktop application.

​
Development Server

yarn suite:dev:desktop
Features:
  • Electron window opens automatically
  • Hot reload for renderer process
  • React DevTools available
  • Source maps enabled
  • Native desktop features enabled
React DevTools Tip: Open DevTools first, then reload the renderer process (Cmd+R or Ctrl+R) to activate React DevTools.

​
Desktop Development Tips

# macOS
Cmd + R

# Windows/Linux
Ctrl + R

​
Trezor Suite Mobile

Mobile development requires additional platform setup for iOS/Android.

​
Start Metro Bundler

yarn native:start
# or
yarn s  # alias
This starts the Metro bundler which serves JavaScript to your mobile app.

​
Run on Android

1

Start Metro Bundler

yarn native:start
2

Reverse Ports (First Time)

yarn native:reverse-ports
# or
yarn ports  # alias
This configures port forwarding for the Android device/emulator.
3

Launch Android App

In a new terminal:
yarn native:android
# or
yarn a  # alias

​
Run on iOS

1

Start Metro Bundler

yarn native:start
2

Launch iOS App

In a new terminal:
yarn native:ios
# or
yarn ios  # alias

​
Mobile Development Commands

CommandAliasDescription
yarn native:startyarn sStart Metro bundler
yarn native:androidyarn aRun on Android
yarn native:iosyarn iosRun on iOS
yarn native:prebuildyarn pRegenerate native projects
yarn native:reverse-portsyarn portsSet up Android port forwarding

​
Connect Examples

Run example implementations of Trezor Connect.

​
Available Examples

The repository includes several Connect integration examples in packages/connect-examples/:
  • webextension - Browser extension integration
  • electron - Electron app integration
  • react - React app integration

​
Running Examples

Each example has its own dev server: 
# Run specific example
yarn workspace @trezor/connect-examples-<example-name> dev

# Example: Run React example
yarn workspace @trezor/connect-examples-react dev

​
Connect Explorer

Interactive API explorer for testing Connect methods. 
yarn workspace @trezor/connect-explorer dev
Open in browser to:
  • Test Connect API methods
  • View request/response data
  • Debug device communication
  • Explore available methods

​
Development Environment Configuration

​
Optional: Enable Developer Tools

Create .env.local in the repository root: 
cp env.local.example .env.local
Edit .env.local: 
# Enable TanStack React Query DevTools
TANSTACK_REACT_QUERY_DEV_TOOLS=true
Restart the dev server after modifying .env.local.

​
Browser DevTools Extensions

Recommended browser extensions:
  • React DevTools - Inspect React component tree
  • Redux DevTools - Debug Redux state (if using Redux)
  • React Query DevTools - Already integrated in app

​
Using Trezor Devices

​
Physical Device

Connect your Trezor device via USB. The app should detect it automatically. Troubleshooting:
  • Ensure device is unlocked
  • Check USB cable connection
  • Try a different USB port
  • On Linux, verify udev rules are installed
Use Trezor User Env to run device emulators. Benefits:
  • No physical device needed
  • Test with multiple models
  • Fast iteration
  • Automated testing support

​
Multiple Apps Simultaneously

​
Run Multiple Development Servers

You can run multiple apps at the same time:
1

Terminal 1: Web App

yarn suite:dev
Runs on http://localhost:8000
2

Terminal 2: Desktop App

yarn suite:dev:desktop
3

Terminal 3: Connect Explorer

yarn workspace @trezor/connect-explorer dev
Each app runs on a different port, so there are no conflicts.

​
Port Configuration

​
Default Ports

ApplicationPortURL
Suite Web8000http://localhost:8000
Connect Explorer(varies)Check terminal output
Metro Bundler8081http://localhost:8081

​
Changing Ports

If a port is already in use, you can:
  1. Kill the process using the port: 
    # Find process
lsof -i :8000

# Kill process
kill -9 <PID>
  2. Configure different port (varies by package)

​
Performance Optimization

​
Faster Development

# Skip TypeScript type-checking during dev
# (it runs in the background but doesn't block HMR)
TSC_COMPILE_ON_ERROR=true yarn suite:dev

​
Exclude from Antivirus

On Windows, exclude the repository from Windows Defender: 
Add-MpPreference -ExclusionPath "C:\path\to\trezor-suite"
This significantly improves build and HMR performance.

​
Troubleshooting

​
Module Not Found Errors

# Rebuild essential libraries
yarn build:essential

# If that doesn't work, rebuild all libraries
yarn build:libs

​
Port Already in Use

# Kill process on port 8000
lsof -i :8000 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Or try a different port (if supported by the package)

​
Hot Module Replacement Not Working

1

Check File Watchers (Linux)

Increase file watcher limit:
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
2

Clear Cache

rm -rf .nx/cache **/.eslintcache **/node_modules/.cache
3

Restart Dev Server

Stop the server (Ctrl+C) and start it again.

​
Desktop App Won’t Launch

# Rebuild desktop dependencies
cd packages/suite-desktop
yarn rebuild

# Clear Electron cache
rm -rf ~/Library/Application\ Support/Electron  # macOS
rm -rf ~/.config/Electron  # Linux

​
Mobile App Connection Issues

# Reset Metro bundler cache
yarn native:start --reset-cache

# Re-reverse ports (Android)
yarn native:reverse-ports

# Rebuild native projects
yarn native:prebuild:clean
yarn native:prebuild

​
Build Fails After Git Pull

# Update submodules
git submodule update --init --recursive

# Pull LFS files
git lfs pull

# Reinstall dependencies
yarn

# Rebuild essential libraries
yarn build:essential

​
Code Quality During Development

​
Linting

# Lint all files
yarn lint

# Lint JavaScript/TypeScript only
yarn lint:js

# Auto-fix linting issues
yarn lint:js:fix-files <file-path>

​
Type Checking

# Check types (full - takes 10-15 minutes)
yarn type-check

# Check types for affected packages only
yarn nx:type-check

​
Formatting

# Format all files
yarn format

# Format specific files
yarn g:prettier --write <file-path>

# Check formatting
yarn format:verify
Run formatting before committing. Pre-commit hooks will enforce this.

​
Development Workflow

​
Typical Daily Workflow

1

Pull Latest Changes

git pull
git submodule update --init --recursive
2

Update Dependencies (if needed)

yarn
3

Build Essential Libraries (if needed)

yarn build:essential
Only necessary if:
  • First time running
  • Switching branches with dependency changes
  • After pulling major updates
4

Start Development Server

yarn suite:dev          # For web
# or
yarn suite:dev:desktop  # For desktop
5

Make Changes and Test

Edit code - changes appear automatically with HMR.
6

Format and Lint Before Committing

yarn g:prettier --write <changed-files>
yarn g:eslint --fix <changed-files>

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us