Monorepo Full-Source Strategy for Mobile Development: Challenges, Solutions, and Practice

Mobile Development Status

In the wave of componentization, the company introduced multi‑repo development to decouple architecture and reuse cross‑business capabilities, supplemented by binary component compilation for speed. As the codebase grew, several drawbacks of multi‑repo binaries became evident:

Low merge efficiency: merging now involves the main repo and many components, each requiring a pipeline run, MR locks, and possible re‑runs, leading to CI complexity and merge queue times exceeding 6 hours.

Dependency‑management issues: stability becomes the product of many repos; even with 99.9 % success per repo, overall install success drops to ~74 %; version traceability suffers due to dynamic resolution.

Reduced code visibility and control: cross‑component refactoring is hard, static analysis is impossible, and local development experience degrades, requiring extra tools to maintain visibility.

Although multi‑repo implements componentization, the numerous optimization tools only address local problems and cannot further improve overall efficiency, especially for super‑apps like Toutiao, Douyin, and Feishu.

To ensure long‑term stability and solve root problems, the company proposes a complete single‑repo solution.

Monorepo Full‑Source Concept and Pros/Cons

Monorepo (Mono Repository) means storing the source code and configuration of multiple related projects or modules in a single version‑control repository, using a unified build and deployment system.

Full Source refers to keeping the entire software system's source code in one repository, providing a single source of truth.

The concept is usually linked with Monorepo; the diagram contrasts MULTI‑REPO (each component in its own Git repo) with MONO‑REPO (components merged into the main repo, a single Git).

2.1 Advantages

Facilitates code reuse: a single repo makes it easy to abstract common functionality into shared libraries.

Simplifies dependency management: all dependencies reside in the same codebase, easing build and management.

Atomic commits: multiple projects can be changed atomically, avoiding version‑compatibility issues.

Large‑scale refactoring: developers can access the whole codebase, making refactoring safer.

Cross‑team collaboration: source‑code dependencies improve flexibility across teams.

Improved engineering quality: an open, transparent, shared culture boosts developer growth and code quality.

2.2 Disadvantages

Version information loss: a single version number cannot represent individual project versions.

Lack of access control: all code is in one repo, raising potential security concerns.

Disk‑space consumption: checking out the whole repo requires more storage.

Monorepo Full‑Source Practice at ByteDance

BitSky is the internal code‑name for the Monorepo full‑source project, aiming to build a Monorepo infrastructure for client development and improve efficiency and experience. Business teams integrate via the BitSky tool suite.

The suite includes: Merge Suite to help teams migrate smoothly to Monorepo; Build Service to ensure efficient, stable builds under Monorepo; Engineering Architecture to replace tools like CocoaPods with a unified dependency‑layer service; Developer Tools providing a unified GUI for local development.

3.1 Merge Suite: Merging Repositories

The primary task is to migrate existing repos to Monorepo. Because migration involves many teams, the project adopted a phased, gray‑scale approach, comprehensive risk assessment, and tooling support.

The migration proceeds in three stages:

Pre‑migration: evaluate expected benefits using DevOps metrics and build an experimental repo for technical research.

Gray‑scale stage: both multi‑repo and single‑repo development are supported to ensure smooth transition.

Launch stage: use DevOps metrics and NPS surveys to validate benefits.

Git performance challenges caused by repository size are mitigated through configuration tuning and a traffic‑warming strategy to reduce GitLab load on launch day.

3.2 Build Service: Migrating Build System

Xcode's built‑in build system has weak caching, closed source, and no distributed support, leading to limited performance for large apps (≈30,000 compile units). After evaluating alternatives, Bazel was chosen, following the “{Fast, Correct} Choose Two!” principle.

{Fast, Correct} Choose Two！

Build Configuration Migration

In the multi‑repo model, build rules are described with xcodeproj and podspec; Bazel uses BUILD and WORKSPACE files. Two tools were created:

BazelGenerator : translates existing build parameters and dependencies into Bazel rules.

BUILD DSL : provides a semantic, easy‑to‑learn DSL for BitSky's build configuration.

bitsky_library(
  name = "Common",
  hdrs = [":Module_hdrs"],
  srcs = [":Module_srcs"]
)

Distributed Capability Construction

Bazel's excellent distributed features were leveraged to implement distributed caching, multi‑level caches, edge nodes, and pre‑caching strategies, significantly improving build efficiency.

Artifact Consistency Verification

Universal deterministic builds ensure that builds on any platform, with any compiler or linker, produce identical artifacts, reducing environment‑induced issues and improving reproducibility and verifiability.

A verification tool aligns resources and symbols at the executable level and normalizes image and text resources inside application bundles.

Unit, integration, and regression tests are also required for release.

3.3 Engineering Architecture: Managing Dependencies

Under multi‑repo, CocoaPods not only manages dependencies but also handles binary integration, hmap optimization, and mixed‑language support. After migrating to Bazel, these functions are naturally provided by the build system.

In the Monorepo full‑source model, third‑party components reside inside the repo, making CocoaPods unsuitable; a lightweight dependency manager was built to replace it, solving three major problems:

Dependency issues: conflicts, downloads, resolution, and repository outages are eliminated.

Slow builds: removing CocoaPods avoids repeated downloading and compiling of dependencies.

Single source of truth: the main repo becomes the unique version source, avoiding binary/source mismatches.

Removing CocoaPods does not abandon componentization; verification and layering services for components are still provided.

3.4 Developer Tools: Optimizing Local Experience

Xcode is the primary IDE for iOS development but lacks good support for external build systems and struggles with large codebases (10k‑100k files), resulting in slow response and limited customization.

Custom tools—Tulsi, BuildService, and IndexImport—were developed to fill gaps in indexing, syntax highlighting, logging, and progress display, making Xcode usage comparable to native workflows and greatly improving usability.

Beyond these modules, BitSky integrates the company's DevOps platform and the Hummer monitoring system to provide full‑chain metrics, alerts, and a complete Monorepo development experience.

Data Benefits

After merging repositories for Toutiao and Feishu, the following benefits were observed (example from Feishu):

Build efficiency improvements: after migrating the build system for Toutiao, PCT50 compile time dropped 20 % and PCT90 dropped 50 %; overall build time (including Pods) decreased by 50 %.

Conclusion

5.1 Problems and Challenges

The practice chapter outlines core modules of the solution, but many execution‑level details remain unexplored. Common challenges include maintaining componentization under Monorepo, dependency layering, and anti‑degradation measures, while project‑specific issues may not be universally applicable. Future work will explore VFS, multiple build systems, and multi‑platform single‑repo approaches.

5.2 Our Experience

The Monorepo full‑source approach is not suitable for every mobile project; large architectural changes depend on organizational communication structures (Conway's Law). Nevertheless, such migrations are essential for continuous technical progress, efficiency gains, and business competitiveness.

We will contribute our tooling back to the Bazel community and publish a series of articles describing the BitSky workflow and principles.

Reference articles:

https://engineering.atspotify.com/2022/11/strategies-and-tools-for-performing-migrations-on-platform/

https://en.wikipedia.org/wiki/Conway%27s_law