Angular CLI Workspaces: Managing Multiple Projects

Anton Ioffe - November 23rd 2023 - 9 minutes read

In the rapidly evolving landscape of web development, the Angular CLI stands as a cornerstone tool, offering unparalleled efficiencies, particularly when maneuvering through the intricacies of multi-project workspaces. In this deep dive, you—seasoned developers—will traverse the nuanced anatomy of Angular CLI workspaces, unearthing the power of streamlined project configurations, the art of crafting shared code libraries, and mastering the orchestra of commands at your fingertips to fuel a robust development workflow. We’ll then scale those strategic heights, aligning with enterprise demands, by harnessing the full potential of Angular for building, integrating, and deploying colossal applications with precision. Prepare to elevate your project management acumen to an architectural symphony that orchestrates multiple projects with harmonious ease and technical finesse.

The Anatomy of Angular CLI Workspaces

At the heart of every Angular CLI workspace lies a crucial file: angular.json. This configuration file serves as both the brains and the blueprint for the workspace, instructing the CLI on how to handle builds, testing, serving, and other tasks across all contained projects. An Angular workspace is a cohesive environment where multiple applications and libraries live together, sharing dependencies and tools. Its modularity not only aids in organizing the codebase but also streamlines processes, allowing for concurrent development on related projects within a single repository.

Within an Angular CLI workspace, the distinction between applications and libraries is paramount. Applications are executable projects that can be built, served, and deployed. They are often the end product delivered to the client. Libraries, on the other hand, are collections of reusable code that applications can depend on. By design, libraries are intended to be imported into applications, promoting code reuse and modularity. Both types of projects are nestled within the projects directory of the workspace, each with its own specific configuration nested in ‘angular.json’ under its project name.

The workspace structure revolves around shared configurations and project-specific settings, all residing harmoniously in angular.json. This single file provides workspace-wide defaults which can be overridden for individual projects, thereby granting flexibility while maintaining consistency. The configuration entails schematics for generating and building projects, options for the Angular CLI itself, and project-level settings like builder configurations for scripts, styles, and assets. This approach significantly lowers the complexity that typically accompanies large codebases by centralizing configuration management.

One of the fundamental advantages of Angular CLI workspaces is the ability to scale to multiple projects while maintaining a single node_modules directory at the workspace's root. This design not only reduces disk space usage but also diminishes the installation and updating overhead of dependencies. By centralizing the management of these dependencies, developers enjoy a more consistent development environment across all projects, smoothening the workflow and reducing the likelihood of version conflicts or duplication.

However, with great power comes great responsibility, and maintaining an angular.json file demands diligence and precision. Common coding mistakes include misconfigurations of builder options or incorrect paths to assets and styles. For instance, developers might inadvertently specify a wrong output path in a build option that leads to deployment issues or forget to include glob patterns for assets, which results in missing files during runtime. Correcting such mistakes typically involves reassessing each project's configuration against the workspace schema, ensuring all paths and options are accurately defined and reference existing files. This meticulous review can safeguard against configuration-induced bugs and keep the workspace functioning as a unified, efficient development machine.

Setting Up a Multiproject Workspace

Initiating an Angular workspace tailored for handling multiple projects begins with the execution of the Angular CLI command ng new workspace-name --create-application=false. This command scaffolds a new workspace without immediately generating an application, providing a clean slate for setting up multiple discrete projects. It is a foundational step that constructs the necessary directory structure and configuration files.

Once the initial workspace is established, adding applications to the workspace is straightforward. Utilize the command ng generate application project-name to scaffold a new application within the workspace. This creates a separate directory under the projects folder, keeping the codebase organized and segmented by function or purpose.

Configuring each application to meet specific requirements is done within the angular.json file. Here, one can adjust various settings like build options, file replacement strategies, and environment-specific configurations for each project. Best practices entail structuring the angular.json with readability in mind, grouping and commenting configurations logically to ensure that changes are easy to follow and maintain.

Within this multiproject context, the Angular CLI offers a powerful feature to further organize and streamline the development process: shared libraries. A shared library is created using the command ng generate library shared-lib-name, which places the library in the projects directory. Import this library into any application that requires its functionality to promote code reusability and maintain a DRY (Don't Repeat Yourself) codebase.

As the workspace grows, maintaining a consistent project folder structure is imperative. The best-practice approach is to name folders and files descriptively, preserving a clear hierarchy that reflects the architectural layout of the applications and libraries. This attention to detail assures that new and existing team members alike can navigate the codebase with minimal friction, thus safeguarding the workspace's scalability and developer experience.

Code Reusability Strategies with Angular Libraries

Angular libraries are pivotal in ensuring that common functionalities across multiple projects are not replicated unnecessarily. The creation of a library begins with the ng generate library library-name command, which scaffolds out a structured library within the workspace. This practice aids in consolidating shared directives, pipes, services, components, or models. A fundamental principle here is creating a clean API for the library, meaning the library's public API should be well-documented and deliberately exposed, thereby safeguarding against unwarranted dependencies on internal structures which might change.

One of the primary benefits of this setup is its impact on dependency management. By promoting shared logic to libraries, dependencies can be managed at the library level, rather than across multiple projects. This minimizes the risk of version mismatches and simplifies the update process. However, it also requires vigilant monitoring of library versions, as an update to a library can have far-reaching implications across all dependent projects. Consider using semantic versioning to communicate the nature of changes in the library codebase. A patch or minor update indicates backward-compatible changes, whereas a major version implies breaking changes that consumers need to be aware of.

Namespacing plays a critical role in maintaining orderly codebases, especially as the number of libraries in a workspace grows. A consistent naming convention should be adopted to easily identify the purpose and scope of each library. This practice aids in avoiding naming collisions and enhances discoverability. For example, prefixing library names with a company-specific identifier or functional category can assist in this organizational strategy. Nonetheless, over-segmentation should be avoided to prevent an explosion of granular libraries that could make the system more complex to understand and manage.

A consistent API surface across internal libraries is crucial for ease of use. Breaking changes should be minimized and, where necessary, should be communicated clearly through deprecation strategies and migration paths to assist developers in updating their applications. Furthermore, strive for immutability in public interfaces; once a pattern or service is published, changes should be backward-compatible or introduced in a new major version to prevent disruptions in dependent applications.

Finally, while the goal is to maximize code reuse, it’s essential to recognize when not to share code through a library. Sometimes, the overhead of maintaining a library might not justify its use, especially if the functionality is too specific or subject to frequent changes. Thus, a balance must be struck between DRY (Don't Repeat Yourself) practices and the practicality of sharing code. Reusability should not compromise the flexibility nor lead to tightly coupled codebases where changes ripple through multiple projects uncontrollably. Hence, careful evaluation is crucial to decide the granularity and scope of shared libraries.

Streamlining the Development Workflow in Multi-Project Environments

In a multi-project Angular CLI workspace, effective management and workflow are essential to meet the development demands without compromising on productivity. The Angular CLI streamlines these processes by providing a suite of commands designed to work across multiple projects simultaneously. For instance, the ng build command can be configured to compile multiple applications conditionally based on defined criteria within your CI/CD scripts, ensuring that only the modified projects are rebuilt, which saves time during the deployment process. Similarly, ng test can be invoked to execute unit tests across multiple projects, leveraging Angular CLI's built-in capabilities to handle parallel processing, thus speeding up the testing phase.

To prevent namespace collisions, a common mistake when dealing with multiple projects, developers must follow a systematic naming convention for components, directives, services, and modules. A proactive approach is to prefix project-specific features with unique identifiers. When it comes to misconfigurations, such issues often arise from incorrect assumptions about the default working directory. Ensuring that all paths for scripts, styles, and assets are relative to the root of each specific project within the workspace can avoid such pitfalls.

In addition to a solid naming strategy, script automation plays a pivotal role in smoothing the development workflow. Utilizing npm scripts or similar task runners to abstract complex CLI command chains enhances consistency and reduces manual error. For example, developers can create a custom npm run build-all command that triggers build processes for all projects, thereby codifying the build logic and making it less susceptible to individual developer preferences or mistakes.

Environment consistency is another essential factor often overlooked. Using environment-specific configuration files that can be passed to the Angular CLI commands can ensure that developers work in a set up that closely mimics the production environment. This can be achieved through the ng serve, ng build and ng test commands with the --configuration flag. Setting up these configurations correctly from the start can save countless hours otherwise spent on debugging environment-specific issues.

Moreover, enforcing a code-linting strategy across all projects within the workspace helps maintain code quality and ensure adherence to standards. Running ng lint on a pre-commit hook, or as part of the CI process, can catch potential errors and stylistic issues before they become entrenched in the codebase. With these practices, developers can focus on delivering features rather than getting bogged down in the intricacies of multi-project workspace management.

Scaling and Continuous Integration for Enterprise-Level Angular Projects

Strategically scaling and maintaining efficiency during continuous integration poses unique challenges in large-scale Angular projects. With enterprise-level applications, it’s paramount to optimize build times to facilitate rapid deployment cycles. Incorporating caching mechanisms such as incremental builds can significantly reduce build times by only recompiling code that changed since the last build, as opposed to rebuilding the entire application. Leveraging Angular CLI’s parallelization options further enhances performance by distributing workload across multiple cores or machines. Configurations for such optimizations are maintained under specific build options, ensuring consistency across different environments and developers.

Continuous integration systems must also be designed to maintain a high level of code quality. One approach is setting up pre-commit hooks that run a series of checks before code is even integrated into the main branch. On top of this, Continuous Integration services should be configured to execute linters, formatters, and a full suite of automated tests upon each pull request. What’s more, conditionally executing different categories of tests—for instance, running end-to-end tests only when changes are made to UI components—can save valuable time, allowing for quicker feedback loops.

When it comes to managing releases across various environments such as development, staging, and production, maintaining separate configuration files for each is critical. Advanced workspace setups include scripts to automatically bump versions, tag commits, and generate changelogs, ensuring that the deployment process is as seamless as possible. Implementing feature toggles controlled through these configurations enables selective feature deployment, which is useful for A/B testing, canary releases, or rolling back features without reverting entire deployments.

Furthermore, automated deployment pipelines are essential for scalable Angular projects. These pipelines should be configured to handle everything from code integration to production rollouts, with automated gates at various stages to ensure that all quality benchmarks are met. Setting up Docker containers as part of the CI pipeline can immensely streamline the deployment to different servers, guaranteeing that the application runs smoothly in a consistent environment across all stages of development.

Finally, addressing advanced workspace configurations includes the use of custom Angular Builders or integration with third-party tools for specific tasks such as static code analysis, artifact storage, and performance monitoring. Dedicating time to crafting these workspace tools is a worthwhile investment. This not only saves developer effort in the long run but also promotes a culture of continuous improvement, pushing the performance and reliability of enterprise-level Angular projects to new heights.


The article explores the power of Angular CLI workspaces in managing multiple projects, highlighting the benefits of streamlined project configurations, code reuse through shared libraries, and efficient development workflows. The key takeaways include the importance of maintaining a well-structured angular.json file, leveraging shared libraries for code reusability, and implementing strategies to streamline the development workflow in multi-project environments. The challenging technical task for readers is to set up a multi-project Angular CLI workspace, create and integrate a shared library into an application, and optimize the development workflow through automation and environment-specific configurations.

Don't Get Left Behind:
The Top 5 Career-Ending Mistakes Software Developers Make
FREE Cheat Sheet for Software Developers