Building Angular Apps in an Nx Monorepo

In this tutorial you'll learn how to use Angular with Nx in a monorepo (integrated) setup.

What are you going to learn?

• how to create a new Angular application
• how to run a single task (i.e. serve your app) or run multiple tasks in parallel
• how to leverage code generators to scaffold components
• how to modularize your codebase and impose architectural constraints for better maintainability

Nx CLI vs. Angular CLI

Nx evolved from being an extension of the Angular CLI to a fully standalone CLI working with multiple frameworks. As a result, adopting Nx as an Angular user is relatively straightforward. Your existing code, including builders and schematics, will still work as before, but you'll also have access to all the benefits Nx offers.

Advantages of Nx over the Angular CLI:

• Cache any target
• Run only tasks affected by a code change
• Split a large angular.json into multiple project.json files
• Integrate with modern tools
• Controllable update process

Visit our "Nx and the Angular CLI" page for more details.

Warm Up

Here's the source code of the final result for this tutorial.

Creating a new Angular Monorepo

Create a new Angular monorepo with the following command:

Let's name the initial application angular-store. In this tutorial we're going to use cypress for e2e tests and css for styling. The above command generates the following structure:

The setup includes..

• a new Angular application (apps/angular-store/)
• a Cypress based set of e2e tests (apps/angular-store-e2e/)
• Prettier preconfigured
• ESLint preconfigured
• Jest preconfigured

Typically, an integrated Nx workspace places application projects in the apps folder and library projects in the libs folder. Applications are encouraged to be as light-weight as possible so that more code is pushed into libraries and can be reused in other projects. This folder structure is just a suggestion and can be modified to suit your organization's needs.

The nx.json file contains configuration settings for Nx itself and global default settings that individual projects inherit. The apps/angular-store/project.json file contains settings that are specific to the angular-store project. We'll examine that file more in the next section.

Serving the App

To serve your new Angular application, just run:

Your application should be served at http://localhost:4200.

Nx uses the following syntax to run tasks:

All targets, such as serve, build, test or your custom ones, are defined in the project.json file.

Each target contains a configuration object that tells Nx how to run that target.

The most critical parts are:

• executor - this is of the syntax <plugin>:<executor-name>, where the plugin is an NPM package containing an Nx Plugin and <executor-name> points to a function that runs the task.
• options - these are additional properties and flags passed to the executor function to customize it

Learn more about how to run tasks with Nx. We'll revisit running tasks later in this tutorial.

Adding Another Application

Nx plugins usually provide generators that allow you to easily scaffold code, configuration or entire projects. To see what capabilities the @nx/angular plugin provides, run the following command and inspect the output:

Run the following command to generate a new inventory application. Note how we append --dry-run to first check the output.

As you can see, it generates a new application in the apps/inventory/ folder. Let's actually run the generator by removing the --dry-run flag.

Sharing Code with Local Libraries

When you develop your Angular application, usually all your logic sits in the app folder. Ideally separated by various folder names which represent your "domains". As your app grows, however, the app becomes more and more monolithic and the code is unable to be shared with other applications.

Nx allows you to separate this logic into "local libraries". The main benefits include

• better separation of concerns
• better reusability
• more explicit "APIs" between your "domain areas"
• better scalability in CI by enabling independent test/lint/build commands for each library
• better scalability in your teams by allowing different teams to work on separate libraries

Creating Local Libraries

Let's assume our domain areas include products, orders and some more generic design system components, called ui. We can generate a new library for each of these areas using the Angular library generator:

Note how we type out the full path in the directory flag to place the libraries into a subfolder. You can choose whatever folder structure you like to organize your projects. If you change your mind later, you can run the move generator to move a project to a different folder.

Running the above commands should lead to the following directory structure:

Each of these libraries

• has its own project.json file with corresponding targets you can run (e.g. running tests for just orders: nx test orders)
• has the name you specified in the generate command; you can find the name in the corresponding project.json file
• has a dedicated index.ts file which is the "public API" of the library
• is mapped in the tsconfig.base.json at the root of the workspace

Importing Libraries into the Angular Applications

All libraries that we generate automatically have aliases created in the root-level tsconfig.base.json.

Hence we can easily import them into other libraries and our Angular application. As an example, let's create and expose a ProductListComponent component from our libs/products library. Either create it by hand or run

We don't need to implement anything fancy as we just want to learn how to import it into our main Angular application.

Make sure the ProductListComponent is exported via the index.ts file of our products library and is listed in the exports of the ProductsModule. This is our public API with the rest of the workspace. Only export what's really necessary to be usable outside the library itself.

We're ready to import it into our main application now. First (if you haven't already), let's set up the Angular router. Configure it in the app.config.ts.

And in app.component.html:

Then we can add the ProductListComponent component to our app.routes.ts and render it via the routing mechanism whenever a user hits the /products route.

Serving your app (nx serve angular-store) and then navigating to /products should give you the following result:

Let's apply the same for our orders library.

• generate a new component OrderListComponent in libs/orders and export it in the corresponding index.ts file
• import it into the app.routes.ts and render it via the routing mechanism whenever a user hits the /orders route

In the end, your app.routes.ts should look similar to this:

Let's also show products in the inventory app.

Visualizing your Project Structure

Nx automatically detects the dependencies between the various parts of your workspace and builds a project graph. This graph is used by Nx to perform various optimizations such as determining the correct order of execution when running tasks like nx build, identifying affected projects and more. Interestingly you can also visualize it.

Just run:

You should be able to see something similar to the following in your browser.

Notice how shared-ui is not yet connected to anything because we didn't import it in any of our projects.

Exercise for you: change the codebase such that shared-ui is used by orders and products. Note: you need to restart the nx graph command to update the graph visualization or run the CLI command with the --watch flag.

Testing and Linting - Running Multiple Tasks

Our current setup doesn't just come with targets for serving and building the Angular application, but also has targets for unit testing, e2e testing and linting. Again, these are defined in the project.json file. We can use the same syntax as before to run these tasks:

More conveniently, we can also run tasks in parallel using the following syntax:

Caching

One thing to highlight is that Nx is able to cache the tasks you run.

Note that all of these targets are automatically cached by Nx. If you re-run a single one or all of them again, you'll see that the task completes immediately. In addition, (as can be seen in the output example below) there will be a note that a matching cache result was found and therefore the task was not run again.

Not all tasks might be cacheable though. You can configure cacheableOperations in the nx.json file. You can also learn more about how caching works.

Testing Affected Projects

Commit your changes to git.

And then make a small change to the products library.

One of the key features of Nx in a monorepo setting is that you're able to run tasks only for projects that are actually affected by the code changes that you've made. To run the tests for only the projects affected by this change, run:

Note that the unit tests were run for products, angular-store and inventory, but not for orders because a change to products can not possibly break the tests for orders. In a small repo like this, there isn't a lot of time saved, but as there are more tests and more projects, this quickly becomes an essential command.

You can also see what projects are affected in the graph visualizer with;

Building the Apps for Deployment

If you're ready and want to ship your applications, you can build them using

All the required files will be placed in dist/apps/angular-store and dist/apps/inventory and can be deployed to your favorite hosting provider.

You can even create your own deploy task that sends the build output to your hosting provider.

Replace the command with whatever terminal command you use to deploy your site.

The "dependsOn": "build" setting tells Nx to make sure that the project's build task has been run successfully before the deploy task.

With the deploy tasks defined, you can deploy a single application with nx deploy angular-store or deploy any applications affected by the current changes with:

Imposing Constraints with Module Boundary Rules

Once you modularize your codebase you want to make sure that the libs are not coupled to each other in an uncontrolled way. Here are some examples of how we might want to guard our small demo workspace:

• we might want to allow orders to import from shared-ui but not the other way around
• we might want to allow orders to import from products but not the other way around
• we might want to allow all libraries to import the shared-ui components, but not the other way around

When building these kinds of constraints you usually have two dimensions:

• type of project: what is the type of your library. Example: "feature" library, "utility" library, "data-access" library, "ui" library
• scope (domain) of the project: what domain area is covered by the project. Example: "orders", "products", "shared" ... this really depends on the type of product you're developing

Nx comes with a generic mechanism that allows you to assign "tags" to projects. "tags" are arbitrary strings you can assign to a project that can be used later when defining boundaries between projects. For example, go to the project.json of your orders library and assign the tags type:feature and scope:orders to it.

Then go to the project.json of your products library and assign the tags type:feature and scope:products to it.

Finally, go to the project.json of the shared-ui library and assign the tags type:ui and scope:shared to it.

Notice how we assign scope:shared to our UI library because it is intended to be used throughout the workspace.

Next, let's come up with a set of rules based on these tags:

• type:feature should be able to import from type:feature and type:ui
• type:ui should only be able to import from type:ui
• scope:orders should be able to import from scope:orders, scope:shared and scope:products
• scope:products should be able to import from scope:products and scope:shared

To enforce the rules, Nx ships with a custom ESLint rule. Open the .eslintrc.base.json at the root of the workspace and add the following depConstraints in the @nx/enforce-module-boundaries rule configuration:

To test it, go to your libs/products/src/lib/product-list/product-list.component.ts file and import the OrderListComponent from the orders project:

If you lint your workspace you'll get an error now:

If you have the ESLint plugin installed in your IDE you should immediately see an error:

Learn more about how to enforce module boundaries.

Setting Up CI

Without adequate tooling, CI times tend to grow exponentially with the size of the codebase. Nx helps decrease the average CI time with the affected command and Nx Cloud's distributed caching. Nx also decreases the worst case CI time with Nx Cloud's distributed task execution.

To set up Nx Cloud run:

And click the link provided. You'll need to follow the instructions on the website to sign up for your account.

Then you can set up your CI with the following command:

This will create a default CI configuration that sets up Nx Cloud to use distributed task execution. This automatically runs all tasks on separate machines in parallel wherever possible, without requiring you to manually coordinate copying the output from one machine to another.

Next Steps

Here's some more things you can dive into next:

• Read more about how Nx compares to the Angular CLI
• Learn more about the underlying mental model of Nx
• Learn about popular generators such as how to setup Tailwind
• Learn how to migrate your existing Angular CLI repo to Nx
• Setup Storybook for our shared UI library
• Speed up CI: Run only tasks for project that got changed
• Speed up CI: Share your cache
• Speed up CI: Distribute your tasks across machines

Also, make sure you

• Join the Official Nx Discord Server to ask questions and find out the latest news about Nx.
• Follow Nx on Twitter to stay up to date with Nx news
• Read our Nx blog
• Subscribe to our Youtube channel for demos and Nx insights