[Feature] Document the monorepo architecture, build process and dependencies

[ottok]

I have been trying to reproduce the build of OneKey. My goal is to build the Chrome extension and the Electron app in a clean Debian/Ubuntu container. However, I find it challenging to understand the build process. Could you please create a BUILD.md that explains things such as:

• the monorepo architecture, what is OneKey's code, what are external dependencies
• how are those dependencies downloaded and from where
• if the build is done offline, how can those dependencies be listed and downloaded in advance
• how can the build be instructed to only build a subset of the artifacts (mainly only the Chromium extension and Electron app for Linux)

There are many oddities that are hard to understand. Why for example do you need rimrafto delete files, why isn't a regular rm -rf enough? Why is there a zip.js wrapper, why not call zip directly? What is the purpose of cross-env?

I have documented some things I've uncovered so far in https://github.com/OneKeyHQ/app-monorepo/compare/x...ottok:onekey-app-monorepo:build-audit, but understanding the repository structure by purely reading the build files seems overly complex, so I was hoping maybe you can produce some documentation on the topic. Thanks!

[originalix]

Hi! Thanks for raising this issue about building OneKey in Ubuntu. Let me explain the build system and address your specific questions:

The monorepo uses Yarn workspaces to manage multiple apps (desktop, extension, mobile, web) and shared packages. For building in Ubuntu, you'll need:

# Install prerequisites
sudo apt-get install -y git curl build-essential python3 libusb-1.0-0-dev libudev-dev

# Setup Node.js 20+ and Yarn
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
corepack enable && corepack prepare [email protected] --activate

# Build steps
git clone https://github.com/OneKeyHQ/app-monorepo.git
cd app-monorepo
yarn install
yarn workspace @onekeyhq/ext build:v3      # Chrome extension
yarn workspace @onekeyhq/desktop build      # Desktop app

About your specific questions:

• rimraf: Used instead of rm -rf for consistent behavior across Windows/Linux/Mac and better handling of file permissions
• cross-env: Ensures environment variables work consistently across different shells and platforms
• zip.js: Handles browser-specific packaging requirements and version management for extensions

Common issues:

• Node.js version conflicts: Use n version manager
• Permission errors: Check node_modules ownership
• Missing dependencies: Install build-essential package

The build process works offline after initial setup since all dependencies are managed through yarn.lock.

Let me know if you run into any specific issues!

[originalix]

Actually, we haven't tested whether it compiles successfully in Docker. If you run into issues there, you'll need to address them based on the specific errors you get.

[ottok]

Thanks for a quick reply and sharing more context. I actually am already able to successfully build in a container (reproducible build code at https://github.com/OneKeyHQ/app-monorepo/compare/x...ottok:onekey-app-monorepo:build-audit). Exact steps how to build is visible in the OneKey CI scripts, so I mainly read them to reproduce the steps. I was however not able to spot inline comments or a README explaining why the build steps are what they are.

My question was more about understanding what the architecture is and why it is so. It is much easier to contribute improvements if one grasps the design decisions of the original authors.

[originalix]

Hi, thanks a lot for your submission! Here's the design background of our monorepo. Feel free to discuss any questions you might have at any time.

We use a monorepo + workspaces because it lets us share critical crypto/blockchain code across platforms while keeping platform-specific stuff separate. This means:

• Core crypto logic stays consistent everywhere
• Teams can work independently on their platform
• Dependencies are managed centrally
• Changes can be tested across all platforms

The build system complexity comes from needing to support multiple platforms while ensuring consistent behavior for all developers. Each workspace can build independently, making it faster to test changes.