The pros and cons of using monorepos

When to choose a monorepo approach?

Fundamentally, monorepos ensure unified tooling, configurations and scripts. As a single, centralized storage repository, a monorepo promotes consistency in coding practices. The ability to encompass an entire codebase in one place, including libraries and other services, contrasts with traditional monolithic approaches where each project generally relies on its own unique code source. However, while monorepos ensure greater visibility, increased collaborations and more dynamic workflows, adoption might not be the right fit for every team.

Tightly coupled code, longer build times and developer mismanagement can pose significant challenges, especially for less experienced contributors. For example, monorepos can be powerful at a small scale, but quickly become a liability due to multi-gigabyte repo sizes and voluminous source code, which is often serially retested, creating bottlenecks that impede delivery. To counter these deficits, developers can deploy smart build systems -- e.g. Bazel, Nx, Gradle, Lage, etc. -- within a monorepo to use caching, testing and intelligent change detection.

One of the primary reasons for choosing a monorepo is to avoid the risks posed by maintaining separate repositories where system knowledge is spread across different teams or individual developers. Engineering managers can create a consistent, logical structure for build processes by grouping projects and resources in monorepos and removing barriers between development teams, reducing siloed processes and eliminating widespread code duplication.

Team leads should also define uniform policies for naming conventions within monorepos to maintain a consistent state, ensure code readability for disparate tools and reinforce best practices. In terms of using monorepos for microservices, development teams rely on continuous integration and continuous delivery (CI/CD) as well as containers to deploy complex builds. Moreover, automated CI/CD pipelines provide built-in change detection, selective execution and build caching to accelerate monorepo deployments, ensuring that they're both stable and secure. Development teams also employ containers and Dockerfiles to work independently, validate microservices in test environments, and use their preferred tools and programming languages.

Implementation challenges

Monorepos offer benefits such as increased collaboration, visibility and code sharing. However, it's important to first determine a development team's basic strengths and weaknesses to decide if a single repository is the right architectural choice. Consider the following two challenges to monorepo implementation, and ways to approach them.

Maintaining a shared codebase

Minor changes in common code can have unintended consequences on other critical application components that rely on a shared codebase. Logging libraries typically contain frontend/backend functions for tracking errors. Inexperienced developers making changes on an internal CLI tool within that library might neglect to double-check the function status on other application instances.

Once the change has been committed and merged into the main branch, log failures will likely occur across multiple applications with related components breaking at build time. Lacking proper monorepo toolchains, including static analysis, dependency graph tooling and automated testing, can be costly in the long term, affecting a company's brand reputation and time to market. Moreover, organizations need to be able to scale their source control management systems to maintain parity as their codebases and deployments expand.

Avoiding tightly coupled code

Another related challenge common to monorepos is tightly coupled code, which results in an unstructured, intertwined codebase that's difficult to parse. A modular architecture with strict module boundaries along with specialized tooling -- such as NX, Bazel or Pants -- can help establish loose coupling and avoid the complications that result from interdependence. Other issues include duplicate code generation, merge conflicts, slow build/test times and complex microservice updates.

Deploying a single, smart CI/CD pipeline can help resolve those issues. The pipeline enforces consistent dependency versions across all services based on shared build tools and configurations. It also performs integration testing for committed changes, accelerates release cycles and updates, and helps establish consistent build environments. A key benefit is that all microservices are built and tested under identical conditions. Development teams working within a monorepo can organize and group projects together in logically consistent ways, while the automated pipeline reduces the overhead of managing dependencies.

Best practices

Establishing best practices avoids the risk of a monorepo becoming a development liability with unmanageable source code, high numbers of merge conflicts and CI/CD bottlenecks. Some best practices include:

• Evaluate teams. Assess the development culture and determine whether developers possess the collaborative abilities and expertise necessary to manage build processes within a monorepo.
• Implement permissions restrictions. After adoption, establish permission restrictions to control deployment access, create short-lived branches with clear version histories and enforce naming guidelines.
• Eliminate redundancies. Team leads and engineering managers can also implement build caching and incremental builds that include only committed changes to eliminate redundancies, accelerate CI/CD and reduce computation costs.

Capitalizing on monorepos for AI

When deployed to improve AI project outcomes, a synergistic relationship exists between monorepos and AI model training and implementations. On the one hand, development teams increasingly use AI tools to manage monorepo complexity. On the other hand, monorepos provide critical codebase context for cataloging AI project changes, simplifying project dependencies/refactoring, and maintaining well-organized model databases and applications. Effectively, AI maintains AI to improve the technology.

In terms of model training, LLMs rely primarily on contextual cues and corroborations. Developers can use monorepos to maintain all source code in one place for that analysis, as well as offer in-context examples at just the right level of abstraction. An example of this would be using detailed, manageable code samples with high-level architectural summaries to provide the correct training cues.

Engineers also use intelligent monorepo tooling to advance from file-level manipulations to providing AI with clear, navigational codebases and overviews that lead to more effective training and appropriate model responses.

Kerry Doyle writes about technology for a variety of publications and platforms. His current focus is on issues relevant to IT and enterprise leaders across a range of topics, from nanotech and cloud to distributed services and AI.