Trezor Suite is a Yarn (v4) workspaces monorepo built and checked with Nx (nx.json). Root scripts like type-check, test:unit, lint:js, and lint:styles run via yarn nx affected --target=..., so by default they only touch packages changed relative to origin/develop — use the :all variant (e.g. yarn test:unit:all) to run across the whole repo.
Code is organized into four workspace scopes with a strict one-way dependency direction (see the Packages skill):
packages/(@trezor/*) — domain-agnostic libraries and apps:connect(Trezor Connect SDK core, withconnect-web/connect-webextension/connect-mobileproviding the iframe/popup, WebExtension, and mobile entry points around it),transport/transport-bridge/transport-web(device communication),blockchain-link(blockchain backend clients),protobuf/protocol(device wire protocol),components/styles/theme(design system), andsuite-desktop*(Electron shell).suite-common/(@suite-common/*) — business logic shared between the web/desktop and mobile apps (e.g.wallet-core,message-system,device); imports only frompackages/.suite/(@suite/*) — desktop & web app feature code; imports frompackages/andsuite-common/.suite-native/(@suite-native/*) — mobile app (React Native); imports frompackages/andsuite-common/.
Redux: both apps compose their store (see packages/suite/src/reducers/store.ts for web/desktop, suite-native/state for mobile) from @suite-common/wallet-core slices plus their own platform-specific reducers/@suite/* or module-* packages. Follow Redux conventions.
A package may only import from scopes listed above it (e.g. suite can depend on suite-common, never the reverse).
suite-common/AGENTS.md and suite-native/AGENTS.md layer additional mandatory skills (test utilities) on top of this file — check for one when working inside those trees.
All skills are mandatory reading before making changes.
- Basic Syntax – If-else, ternaries, and other syntax rules
- Code Style Guide – How to contribute code style proposals
- Comments – Comment formatting conventions
- Common Issues – Known issues and their solutions
- Components – React component file structure and patterns
- Common Tasks – Dependency management, package creation, and troubleshooting
- Defensive Programming – Exhaustive checks and safe defaults
- Dependency Injection – DI pattern for service definitions, factories, and composition roots
- Development Commands – Running apps, linting, testing, and building
- Git and Commit Guidelines – Conventional Commits format and best practices
- IDB Migrations – Creating IndexedDB storage migrations for the Suite web app
- Import/Export – Named exports and import ordering
- Naming – Naming conventions for variables, functions, and files
- Packages – How to create and structure packages
- Project Overview – What Trezor Suite is and how the monorepo is organized
- Publish Config – publishConfig rules for public npm packages
- Redux – Redux Toolkit patterns and best practices
- Security Headers – Permissions-Policy rationale and previewing the app with production security headers
- Setup Requirements – Prerequisites and initial environment setup
- Tests – Test style guidelines and best practices
- Tests Commands – Running tests and test-related guidelines
- Tests Common – TDD practices for suite-common packages
- Tests Native – TDD practices for suite-native packages
- TypeScript – TypeScript-specific conventions
Account/device confidential data must never leave the device to any external sink (analytics, Sentry, off-device logging, breadcrumbs, request URLs, any remote endpoint). Trace the actual value at the call site, not just the field type, and check the whole repo for outbound reporting.
Confidential (see redactAccount/redactDevice in suite-common/logger/src/utils.ts): device id/label/state, static session id, session_id; account descriptor/xpub/key, addresses, UTXOs, txids; exact balances/amounts; labels and free-form user text; passphrase/seed/PIN/wipe code.
Full detail lives in the Development Commands, Tests Commands, and Setup Requirements skills — this is just the fast path.
# Setup (first time; ~15-20 min)
git submodule update --init --recursive && git lfs install && git lfs pull
nvm install && yarn && yarn build:essential
# Run
yarn suite:dev # web app, http://localhost:8000
yarn suite:dev:desktop # Electron app
yarn native:start # mobile app
# Validate (all affected-only by default; append :all to run repo-wide)
yarn type-check --no-tui
yarn test:unit
yarn lint:js:fix --no-tui && yarn lint:styles --no-tui
yarn workspace @scope/package-name test:unit --coverage=0 file.test.ts # single test file- Build times: Initial setup takes 15-20 minutes; builds can take 10-15 minutes
- Windows: Use Git Bash instead of cmd/PowerShell; consider WSL for better performance
- Testing: Some tests may time out in CI environments without network access
- Hardware wallets: Use trezor/trezor-user-env emulator for development