Building the Project

Overview

Trezor Suite uses a multi-stage build process. You must build core libraries before running applications. The build system uses Webpack for bundling and Nx for task orchestration.

Quick Start

After cloning the repository and installing dependencies:

# Build essential libraries (required before first run)
yarn build:essential

# Build all libraries (optional, for full development)
yarn build:libs

Always run yarn build:essential after cloning or when switching branches with dependency changes.

Build Commands

Essential Builds

Build only the core libraries required for development:

yarn build:essential

This builds:

@trezor/suite-data - Data layer and configuration
@trezor/transport-bridge - Device transport layer
Message system signed configuration

Build time: 3-5 minutesThis is a parallel build that runs multiple tasks simultaneously.

Full Library Build

Build all libraries in the monorepo:

yarn build:libs

This uses Nx to build all packages with the build:lib target.

Build time: 10-15 minutesOnly run this if you’re working on library code or need a complete build.

Incremental Builds with Nx

Build only libraries affected by your changes:

# Build affected libraries
yarn nx:build:libs

# Show which projects are affected
yarn nx:show-affected

Nx determines affected projects by:

Git diff against the base branch
Dependency graph analysis
Build cache status

Nx caching can significantly speed up rebuilds. The cache is stored in .nx/cache.

Application Builds

Web Application

Development Build

Run a development server with hot module replacement:

yarn suite:dev

Runs on http://localhost:8000
Includes source maps
Hot module replacement enabled
Development mode React DevTools

Production Build

Create an optimized production build:

yarn suite:build:web

Output: packages/suite-web/build/

Build time: 5-10 minutesThe production build is minified, optimized, and includes hashed filenames for caching.

Production Preview

Build and serve the production version locally:

yarn suite:build:web:preview

This builds the production version and serves it on localhost with security headers applied (identical to production environment).

Desktop Application

Development Build

Run the Electron app in development mode:

yarn suite:dev:desktop

Features:

Hot reload for renderer process
React DevTools available (press Cmd/Ctrl+R to reload)
Source maps enabled
Development console access

To use React DevTools, open DevTools first, then reload the renderer process (Cmd/Ctrl+R).

Production Build

Build the desktop application:

# Build only (no packaging)
yarn workspace @trezor/suite-desktop build

# Full release build with packaging
./scripts/prepare-desktop-release.sh

Desktop release builds require platform-specific dependencies and code signing certificates.

Mobile Application

Mobile builds require additional platform setup for iOS and Android.

Prebuild Native Projects

Generate native iOS and Android projects:

yarn native:prebuild

Clean prebuild (removes existing native projects):

yarn native:prebuild:clean

Build for Android

yarn native:android

Build for iOS

yarn native:ios

Ad-hoc Build

Create an ad-hoc distribution build:

yarn native:adhoc

Build Configuration

Webpack Configuration

Webpack configs are located in the packages/suite-build package:

packages/suite-build/
├── configs/
│   ├── base.webpack.config.ts      # Common configuration
│   ├── web.webpack.config.ts       # Web-specific
│   └── desktop.webpack.config.ts   # Desktop-specific
├── plugins/                        # Custom plugins
└── utils/                          # Build utilities

Environment Variables

Optional environment configuration using .env.local:

Create .env.local File

cp env.local.example .env.local

Configure Options

# Enable TanStack React Query DevTools
TANSTACK_REACT_QUERY_DEV_TOOLS=true

# Other development flags
# ...

Never commit .env.local - it’s in .gitignore for a reason.

Experimental Builds

Vite Development Build

EXPERIMENTAL - Use for development only, not for production testing.

yarn suite:dev:vite

Features:

Faster hot module replacement
Instant server start
Lightning-fast updates

Limitations:

May not match production behavior exactly
Use yarn suite:dev for production-like development

Build Optimization

TypeScript Compilation

Type-check all packages:

# Full type-check (10-15 minutes)
yarn type-check

# Type-check affected packages only
yarn nx:type-check

# Force complete type-check (purges cache)
yarn type-check:force

Type-checking is separate from builds. The build process uses Babel or esbuild for transpilation, not tsc.

Project References

Update TypeScript project references for optimal incremental builds:

# Update references
yarn update-project-references

# Verify references are correct
yarn verify-project-references

Run this after:

Creating new packages
Changing package dependencies
Modifying tsconfig.json files

Caching

Nx Cache

Nx caches build outputs and test results:

# Clear Nx cache
rm -rf .nx/cache

# Skip cache for a single command
yarn nx run-many --target=build:lib --skip-nx-cache

TypeScript Cache

ESLint and TypeScript use caching for faster runs:

# Clear all caches
rm -rf **/libDev **/.eslintcache

# Purge TypeScript cache
yarn type-check:purge

Build Troubleshooting

Common Issues

# Clear node_modules and reinstall
rm -rf node_modules
yarn

# Rebuild essential libraries
yarn build:essential

Dependency Issues

Check for dependency problems:

# Verify workspace resolutions
yarn check-workspace-resolutions

# Check for unused dependencies
yarn depcheck

# List outdated dependencies
yarn list-outdated

Clean Slate

Start completely fresh:

# Nuclear option: delete all dependencies and caches
yarn deps  # Shortcut for: rimraf **/node_modules && yarn

# Rebuild everything
yarn build:libs

This will take 15-20 minutes but solves most dependency-related issues.

Build Performance Tips

Incremental Builds

Use Nx affected commands - Only rebuild what changed
Skip unnecessary builds - Use build:essential instead of build:libs
Keep Nx cache - Don’t delete .nx/cache unless necessary
Update incrementally - Run yarn frequently to avoid large dependency updates

Development Workflow

# Daily development workflow
yarn suite:dev              # Start dev server (no rebuild needed)

# After pulling changes
git pull
yarn                        # Update dependencies
yarn build:essential        # Rebuild core libraries (only if needed)

# After changing library code
yarn nx:build:libs          # Build affected libraries only

Resource Usage

System Requirements for Building:

RAM: 8GB minimum, 16GB recommended
CPU: Multi-core processor (builds use parallel processing)
Disk: 10GB free space (including node_modules)

Build Scripts Reference

Library Scripts

Command	Description	Time
`yarn build:libs`	Build all libraries	10-15 min
`yarn build:essential`	Build core libraries only	3-5 min
`yarn nx:build:libs`	Build affected libraries	Varies

Application Scripts

Command	Description
`yarn suite:dev`	Web dev server
`yarn suite:dev:desktop`	Desktop dev server
`yarn suite:dev:vite`	Vite dev server (experimental)
`yarn suite:build:web`	Production web build
`yarn suite:build:web:preview`	Build and preview production

Mobile Scripts

Command	Description
`yarn native:prebuild`	Generate native projects
`yarn native:android`	Build for Android
`yarn native:ios`	Build for iOS
`yarn native:adhoc`	Ad-hoc distribution build

Utility Scripts

Command	Description
`yarn update-project-references`	Update TypeScript references
`yarn verify-project-references`	Check TypeScript references
`yarn type-check`	Type-check all packages
`yarn type-check:force`	Type-check with cache purge

Next Steps

Learn how to Run Development Servers
Read about Testing
Review Code Style Guidelines

Setup

Contributing

Packages

Overview

Quick Start

Build Commands

Essential Builds

Full Library Build

Incremental Builds with Nx

Application Builds

Web Application

Desktop Application

Mobile Application

Build Configuration

Webpack Configuration

Environment Variables

Experimental Builds

Vite Development Build

Build Optimization

TypeScript Compilation

Project References

Caching

Nx Cache

TypeScript Cache

Build Troubleshooting

Common Issues

Dependency Issues

Clean Slate

Build Performance Tips

Incremental Builds

Development Workflow

Resource Usage

Build Scripts Reference

Library Scripts

Application Scripts

Mobile Scripts

Utility Scripts

Next Steps

Build docs developers (and LLMs) love

Setup

Contributing

Packages

​Overview

​Quick Start

​Build Commands

​Essential Builds

​Full Library Build

​Incremental Builds with Nx

​Application Builds

​Web Application

​Desktop Application

​Mobile Application

​Build Configuration

​Webpack Configuration

​Environment Variables

​Experimental Builds

​Vite Development Build

​Build Optimization

​TypeScript Compilation

​Project References

​Caching

​Nx Cache

​TypeScript Cache

​Build Troubleshooting

​Common Issues

​Dependency Issues

​Clean Slate

​Build Performance Tips

​Incremental Builds

​Development Workflow

​Resource Usage

​Build Scripts Reference

​Library Scripts

​Application Scripts

​Mobile Scripts

​Utility Scripts

​Next Steps

Build docs developers (and LLMs) love

Overview

Quick Start

Build Commands

Essential Builds

Full Library Build

Incremental Builds with Nx

Application Builds

Web Application

Desktop Application

Mobile Application

Build Configuration

Webpack Configuration

Environment Variables

Experimental Builds

Vite Development Build

Build Optimization

TypeScript Compilation

Project References

Caching

Nx Cache

TypeScript Cache

Build Troubleshooting

Common Issues

Dependency Issues

Clean Slate

Build Performance Tips

Incremental Builds

Development Workflow

Resource Usage

Build Scripts Reference

Library Scripts

Application Scripts

Mobile Scripts

Utility Scripts

Next Steps