Monorepo Structure

Trezor Suite is organized as a monorepo using Yarn workspaces, containing multiple applications and shared packages. This structure enables code sharing, consistent tooling, and unified development workflows.

Overview

The repository contains three main projects:

Trezor Connect

Developer API for integrating Trezor into third-party applications

Trezor Suite

Desktop and web application for managing Trezor hardware wallets

Suite Mobile

Native mobile application for iOS and Android

Workspace Configuration

The monorepo uses Yarn 4.12.0 with workspace configuration defined in package.json:

{
  "workspaces": {
    "packages": [
      "packages/*",
      "packages/connect-examples/*",
      "suite-native/*",
      "suite-common/*",
      "suite/*",
      "scripts"
    ]
  }
}

Node.js version 24 is required, managed via NVM. See the .nvmrc file in the repository root.

Directory Structure

High-Level Layout

trezor-suite/
├── packages/          # 📦 Core libraries and tools
├── suite/             # 🖥️ Desktop & web application
├── suite-native/      # 📱 Mobile application
├── suite-common/      # 🤝 Shared code between Suite & Mobile
├── docs/              # 📖 Documentation
├── scripts/           # 🔧 Build and automation scripts
├── docker/            # 🐳 Docker configurations
└── submodules/        # 🔗 Git submodules (firmware, etc.)

Packages Directory

The packages/ directory contains core libraries, Trezor Connect, and reusable components.

Key Packages

Connect Packages
Suite Packages
Shared Libraries
Other Packages

@trezor/connect

Main Connect API

Entry point for all Trezor Connect functionality
Version 9 (rewritten for Suite monorepo)
Used by both Suite and third-party integrations

Location: packages/connect/Documentation

@trezor/connect-web

Web-specific Connect implementation

Browser-compatible version
Uses WebUSB for device communication
Loaded as JavaScript module in Suite Web

Location: packages/connect-web/

@trezor/connect-mobile

Mobile Connect implementation

React Native compatible
Uses native USB/Bluetooth transports
Optimized for mobile platforms

Location: packages/connect-mobile/

@trezor/connect-explorer

Interactive API explorer

Test Connect methods in browser
Example implementations
Development tool

Location: packages/connect-explorer/

@trezor/suite

Core Suite application

Main application logic
Redux store and state management
Shared UI components
Business logic for wallet operations

Location: packages/suite/

@trezor/suite-desktop

Desktop build target

Electron application wrapper
Native OS integrations
Offline capabilities
Tor support

Location: packages/suite-desktop/Architecture Details

@trezor/suite-web

Web build target

Browser-based version
Production builds with security headers
CDN deployment

Location: packages/suite-web/Architecture Details

@trezor/suite-desktop-core

Electron core functionality

Main process logic
IPC communication
Native module integrations

Location: packages/suite-desktop-core/

@trezor/suite-build

Build tools and configurations

Webpack configurations
Vite configurations (experimental)
Build scripts

Location: packages/suite-build/

@trezor/components

UI component library

Reusable React components
Design system components
Used across Suite Web, Desktop, and Connect Explorer

Location: packages/components/

@trezor/blockchain-link

Blockchain communication

WebSocket connections to blockchain backends
Transaction broadcasting
Balance and history fetching

Location: packages/blockchain-link/

@trezor/device-utils

Device-related utilities

Device state management
Firmware version handling
Model detection

Location: packages/device-utils/

@trezor/utils

General utilities

Common helper functions
Type utilities
Shared constants

Location: packages/utils/

@trezor/connect-common

Connect shared code

Protocol definitions
Shared types
Common utilities

Location: packages/connect-common/

Notable packages in the packages/ directory:

@trezor/coinjoin: CoinJoin privacy features
@trezor/crypto-utils: Cryptographic utilities
@trezor/address-validator: Address validation
@trezor/asset-utils: Asset/token utilities
@trezor/analytics-uploader: Analytics infrastructure
@trezor/transport-bridge: Trezor Bridge communication
@trezor/auth-server: Authentication services
@trezor/bundler-security: Build security tooling

Total packages: 60+ in the packages directory

Suite Directory

The suite/ directory contains packages specific to the desktop and web applications.

suite/
├── analytics/              # Analytics collection
├── e2e/                    # End-to-end tests (Playwright)
├── experimental/           # Experimental features
├── experimental-feedback/  # Feedback system
├── idb-migration-utils/    # IndexedDB migration tools
├── intl/                   # Internationalization
├── metadata/               # Labeling and metadata sync
├── platform-encryption-electron/
├── platform-encryption-webauthn/
├── sentry/                 # Error tracking
├── suite-sync/             # Cloud sync features
├── test-utils/             # Testing utilities
├── trading/                # Exchange integrations
└── tx-simulation/          # Transaction simulation

These packages are specific to Suite Desktop and Suite Web, and are not used in Suite Mobile.

Suite Native Directory

The suite-native/ directory contains the mobile application and its modules.

Structure

suite-native/
├── app/                    # 👑 Main mobile application
├── accounts/               # Account management
├── alerts/                 # Alert system
├── analytics/              # Mobile analytics
├── atoms/                  # UI primitives (Jotai atoms)
├── biometrics/             # Biometric authentication
├── bluetooth/              # Bluetooth connectivity
├── device/                 # Device management
├── discovery/              # Account discovery
├── firmware/               # Firmware update flows
├── formatters/             # Data formatting
├── icons/                  # Icon library
├── navigation/             # React Navigation setup
├── module-*/               # Feature modules
├── receive/                # Receive flows
├── send/                   # Send flows
├── state/                  # Redux state
├── theme/                  # Theming system
└── ... (90+ packages)

Key Mobile Packages

@suite-native/app

Main mobile application entry point

@suite-native/atoms

UI primitives and design system

@suite-native/navigation

Navigation structure and routing

@suite-native/state

Redux store configuration

Module Organization

Mobile features are organized as self-contained modules with the module-* prefix:

module-home/ - Home screen
module-accounts-management/ - Account management
module-send/ - Send functionality
module-settings/ - Settings screens
module-device-onboarding/ - Device setup flows
module-trading/ - Exchange features
etc.

Each module typically contains:

React components
Navigation screens
Business logic
Tests

Suite Native is built with React Native 0.81.5 and Expo SDK 54.

Learn more about Mobile Architecture

Suite Common Directory

The suite-common/ directory contains code shared between Suite (Desktop/Web) and Suite Native.

Shared Packages

suite-common/
├── wallet-core/           # Core wallet logic
├── wallet-types/          # Shared TypeScript types
├── analytics/             # Analytics abstractions
├── device/                # Device utilities
├── suite-types/           # Suite-wide types
├── suite-constants/       # Shared constants
├── message-system/        # Message system
├── fiat-services/         # Fiat rate services
├── formatters/            # Data formatters
├── connect-init/          # Connect initialization
└── ... (50+ packages)

Key principle: Code in suite-common/ must work on both React (web/desktop) and React Native (mobile).

wallet-core

Redux slices, selectors, and wallet business logic

wallet-types

TypeScript definitions for wallet operations

suite-types

Application-wide TypeScript types

suite-constants

Shared constants and enums

Build System

Package Manager

Yarn 4.12.0 (Berry) with:

Workspace protocol for internal dependencies
Plug’n’Play (PnP) for faster installs
Constraints and policies for consistency

Build Tools

TypeScript
Bundlers
Testing
Nx

TypeScript 5.8.3 used throughout:

Project references for incremental builds
Strict type checking
Path aliases via tsconfig.base.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "esModuleInterop": true
  }
}

Jest 29.7.0 for unit tests:

yarn test:unit

Playwright for E2E tests (Suite Web/Desktop):

cd suite/e2e
yarn test:e2e

Detox for mobile E2E tests:

yarn workspace @suite-native/app test:e2e

Nx 22.4.3 for build orchestration:

Affected command detection
Computation caching
Parallel execution

# Build only affected packages
yarn nx:build:libs

# Test only affected packages
yarn nx:test-unit

# Show affected projects
yarn nx:show-affected

Dependency Management

Workspace Dependencies

Internal dependencies use the workspace:* protocol:

{
  "dependencies": {
    "@trezor/connect": "workspace:*",
    "@suite-common/wallet-core": "workspace:*"
  }
}

Version Resolutions

Critical packages are pinned in the root package.json:

{
  "resolutions": {
    "typescript": "5.8.3",
    "react": "19.1.0",
    "react-native": "0.81.5",
    "electron": "40.1.0"
  }
}

Changes to resolutions affect all packages. Test thoroughly before updating.

Development Workflow

Initial Setup

Clone Repository

git clone [email protected]:trezor/trezor-suite.git
cd trezor-suite

Initialize Submodules

git submodule update --init --recursive
git config --global submodule.recurse true  # Optional but recommended

Set Up Git LFS

git lfs install
git lfs pull

Install Dependencies

nvm install  # Uses .nvmrc
yarn         # Installs all workspace dependencies

Build Essential Packages

yarn build:essential

Common Commands

# Suite Web
yarn suite:dev

# Suite Desktop
yarn suite:dev:desktop

# Suite Mobile
yarn native:start
yarn native:android  # or yarn native:ios

Architecture Patterns

Code Organization Principles

Feature-Based Organization

Packages are organized by feature/domain rather than technical layer:✅ Good:

suite-native/
├── module-send/
│   ├── components/
│   ├── hooks/
│   ├── screens/
│   └── utils/

❌ Bad:

suite-native/
├── components/
├── hooks/
└── screens/

Dependency Direction

Clear dependency hierarchy:

suite-native/app
      ↓
suite-native/module-*
      ↓
suite-common/*
      ↓
packages/*

Lower-level packages never depend on higher-level ones.

Platform Separation

Platform-specific code is isolated:

suite/* - Desktop/Web only
suite-native/* - Mobile only
suite-common/* - Shared across platforms
packages/* - Platform-agnostic when possible

Naming Conventions

Consistent package naming:

@trezor/* - Core libraries, Connect, Suite Web/Desktop
@suite-native/* - Mobile-specific packages
@suite-common/* - Shared platform-agnostic code
@suite/* - Desktop/Web-specific utilities

Performance Considerations

Build Caching

Nx caches build outputs for faster rebuilds

Incremental Builds

TypeScript project references enable incremental compilation

Code Splitting

Webpack splits bundles for optimal loading

Tree Shaking

Unused code is eliminated in production builds

Initial setup takes 15-20 minutes. Incremental builds are much faster thanks to caching.

Next Steps

Explore specific architectures:

Suite Desktop

Electron-based desktop architecture

Suite Web

Browser-based web architecture

Suite Mobile

React Native mobile architecture

For package-specific documentation, check the README files in each package directory.

Get Started

Architecture

​Monorepo Structure

​Overview

Trezor Connect

Trezor Suite

Suite Mobile

​Workspace Configuration

​Directory Structure

​High-Level Layout

​Packages Directory

​Key Packages

​Suite Directory

​Suite Native Directory

​Structure

​Key Mobile Packages

@suite-native/app

@suite-native/atoms

@suite-native/navigation

@suite-native/state

​Suite Common Directory

​Shared Packages

wallet-core

wallet-types

suite-types

suite-constants

​Build System

​Package Manager

​Build Tools

​Dependency Management

​Workspace Dependencies

​Version Resolutions

​Development Workflow

​Initial Setup

​Common Commands

​Architecture Patterns

​Code Organization Principles

​Performance Considerations

Build Caching

Incremental Builds

Code Splitting

Tree Shaking

​Next Steps

Suite Desktop

Suite Web

Suite Mobile

Build docs developers (and LLMs) love

Monorepo Structure

Overview

Workspace Configuration

Directory Structure

High-Level Layout

Packages Directory

Key Packages

Suite Directory

Suite Native Directory

Structure

Key Mobile Packages

Suite Common Directory

Shared Packages

Build System

Package Manager

Build Tools

Dependency Management

Workspace Dependencies

Version Resolutions

Development Workflow

Initial Setup

Common Commands

Architecture Patterns

Code Organization Principles

Performance Considerations

Next Steps