Angular support for Nx Project Crystal

[LayZeeDK]

This thread is a brainstorm for how Angular support could be integrated in the age of Nx Project Crystal. Feel free to contribute your ideas and feedback.

Nx 18 introduces Project Crystal but doesn't change Angular support to be Crystal-like. Instead, this is left for a future Nx version and work hasn't begun at the time of writing as far as I'm aware, making this a great time to collect feedback from the Nx and Angular communities.

Project Crystal guiding principles

The guiding principles of Nx Project Crystal are:

• Minimize changes to project configuration
• Keep workspace layout familiar
• Use existing tooling

Based on these principles, we notice that integrating Nx in a repo should be unobtrusive.

Nx <=18.0 Angular support

In early versions, Nx supported angular.json as-is. In later versions, Nx supported both angular.json and workspace.json with a similar JSON schema. A major change was the introduction of standalone project.json configurations with metadata for each project instead of a workspace-wide angular.json or workspace.json configuration. Migrating from an Angular CLI workspace to an Nx workspace became a major and potentially breaking change. However, this change reduced the merge conflict pains of having a large workspace-wide configuration that changes as more projects are added, Nx tasks are changed, and Nx migrations are run.

Nx Console support for Angular CLI workspaces

For a while, Nx Console supported various features for Angular CLI workspaces with angular.json and no Nx metadata. Later, Nx Console removed Angular CLI workspace support, making Nx migration mandatory. It would be great to add Angular CLI workspace support to Nx Console again.

[LayZeeDK]

Project Angular Crystal

These are my ideas for Angular support in Nx, following the Nx Project Crystal guiding principles.

Objectives

Keep angular.json as-is

We should go back to early days of Nx when angular.json was supported as-is. This will leave full compatibility for existing tooling like the Angular CLI.

To do this, we should infer projects and targets from angular.json while adding tags and other Nx project metadata to project.json files. Of course, non-Angular CLI metadata should also be supported by targetDefaults in nx.json.

A change to angular.json shouldn't affect all projects defined by angular.json.
❓Can changes to the virtual project and task graphs inferred from angular.json make individual projects and tasks affected?

Nx executor support for Angular CLI

If possible, we should be able to run Nx tasks for Angular projects using the Angular CLI for maximum toolchain compatibility, including Nx executors supporting these targets for Angular projects:

• build
• extract-i18n
• lint
• serve
• test

In essence, it should be possible to list Nx executors in angular.json builder targets and run them via the Angular CLI, for example:

angular.json

{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "builder": "@nx/angular:application",
          "options": {
            "//": "(...)"
          }
        }
      }
    }
  }
}

In the terminal, both of the following commands should work.

Angular CLI:

ng build my-app

Nx CLI (cacheable):

nx build my-app

This is possible by using the convertNxExecutor function to create Angular CLI builder targets.

Nx 17 removed Angular CLI schematics and builders from the official Nx Angular plugin, meaning it no longer uses the convertNxGenerator and convertNxExecutor functions to expose APIs consumed by the Angular CLI.

Nx generator support for Angular CLI

Nx generators for Angular projects should be compatible with Angular Schematics to support the Angular CLI for maximum toolchain compatibility.

For example, we should be able to run

ng generate @nx/angular:component nx-generator-from-angular-cli

This is possible by using the convertNxGenerator function to expose Angular Schematics functions and then adding the necessary JSON metadata to an Nx Angular plugin.

Angular schematic support for Nx CLI

Nx CLI should support using Angular Schematics as generators for maximum toolchain compatibility. For example, we should be able to run

nx generate @schematics/angular:component angular-schematic-from-nx-cli

Currently, the wrapAngularDevkitSchematic function supports programmatically calling an Angular schematic from an Nx generator. Alternatively, the externalSchematics function from Angular DevKit is supported.

[jaysoo]

Hey @LayZeeDK, thanks for getting the discussion going.

Here are a few thoughts from our end.

angular.json file

As you mentioned, if we infer projects+targets from angular.json then adopting Nx becomes less intrusive. This is consistent with how we handle other tooling so far with Project Crystal.

So, if we assume angular.json will just work with Nx by adding @nx/angular, then there are some questions and design choices to consider.

1. Do Angular users want to go back to a giant angular.json file? Because one of the pain points individual project.json addressed was not needing to maintain this file.
2. Do we want to support multiple angular.json files in a monorepo? If so, we need consider things like name conflicts in different angular.json files.
3. If we're invoking the Angular CLI to run Angular projects, then does it make sense to still use Nx executors and generators, or do we convert them into builds and schematics? More on this in the next section.

Similarities between Angular CLI and Nx CLI & a migration path

I think part of the difficulties we're facing when it comes to "crystalizing" Angular projects is that the two CLIs are very similar. This is not a coincidence, of course, since Nx CLI took a lot of inspiration from Angular CLI.

We've considered converting our executors into Angular builders, so nx build, nx serve calls the underlying Angular CLI, which calls builders that are native to it.

Generators will always run through Nx. This is consistent across all Nx plugins. I'm not sure if we should make a special case to support Angular schematics natively, as we don't do it for any other tooling. I would like to explore this option more.

One important consideration is that the crystalized setup of Angular projects should be something that existing Nx+Angular projects can migrate to without sacrificing DX. Although we're committed to support existing projects as they are configured now (with project.json, etc.), we don't want to diverge the experience with Project Crystal so much that it blocks existing users from adopting it into their workspace.

Nx Console

We won't be making Angular-specific features in Nx Console, as its purpose is serve as the UI to Nx. I believe that if we address the above issues correctly, then Angular CLI support wouldn't be necessary as tasks should run seamlessly through Nx.

[Jordan-Hall]

1. Do Angular users want to go back to a giant angular.json file? Because one of the pain points individual project.json addressed was not needing to maintain this file.

Simply put never! I hated the merge conflicts and was one of the big reason I've managed to push nx on angular projects for clients.

Do we want to support multiple angular.json files in a monorepo? If so, we need consider things like name conflicts in different angular.json files.

I like keeping project.json inline with the others. I don't want to be teaching users both for a integrated repo. Yes I'm aware Crystal doesn't need it like before but I'm against what would feel like a hack job for angular!

I actually think if you would to gonwith angular.json I use nx alot less and wouldn't recommend it as much

[LayZeeDK]

@Jordan-Hall
I understand why going from standalone project.json files to a single, workspace-wide angular.json file could seem like a step back. project.json files have to be supported to add Nx-specific metadata like project tags and thus it will also be possible to configure an entire project in project.json rather than in angular.json if you don't care about support for Angular CLI and other Angular-only toolchains.

However, Nx Project Crystal is about the ease of adopting Nx and it getting out of the way for existing toolchains. The adoption path and mental shift going from Angular CLI with a single angular.json file to Nx just working with nx.json and optionally Nx-specific metadata in project.json files will feel a lot let obtrusive than the current state of Nx' Angular support.

[jaysoo]

Yes, 100% what @LayZeeDK said. For users who like explicit targets in project.json, and want to avoid a giant angular.json file, we should continue to support it. Crystalizing @nx/angular would be about making the adoption path easier, so running npx nx init would make minimal changes. We could prompt users about migrating angular.json into separate project.json as well (current behavior).

[Jordan-Hall]

What about other tools nest cli what's behavior for that ?

[flobacher]

💯 for compatibility with angular cli.
regarding angular.json.. was there ever any discussion with the guys from the angular-cli team if they are interested in keeping the root angular.json but moving individual project configuration to seperate files.. if references to those files were kept in angular.json the changes on their side should be rather small...

[leosvelperez]

@LayZeeDK thanks for kicking this off, and everyone else for the feedback provided!

I want to provide an update on our plan regarding an Angular Crystal plugin. This has been put together after checking the feedback here, collecting some more feedback at NgConf, and discussing things internally, taking into account some upcoming work to improve onboarding external repositories into an existing Nx workspace.

TL;DR

• We'll provide an Angular Crystal plugin that supports angular.json as-is and will infer tasks from it
• We'll continue to support project.json files like we do today
• @nx/angular generators will continue to only support project.json files and won't handle angular.json:
  • New Nx workspaces and projects will continue to use project.json files with explicit targets (no angular.json)
  • Automated onboarding (nx init) will continue to split the angular.json file into project.json files with explicit targets
• @nx/angular executors will continue to only support project.json files and won't handle angular.json
• Importing external repositories into an existing Nx workspace (upcoming nx import) will keep the angular.json as-is and will use the Angular Crystal plugin to infer tasks from it

The above is what we plan to implement soon. It would allow using the Angular CLI tooling and configuration while benefiting from the Nx core functionalities. For now, it leaves out of scope making any changes to the current generators and executors to support the angular.json file.

Extending the support for angular.json in the future would depend on the usage and community feedback. Please check the next sections for more information.

Main Feedback

First, a summary of the main feedback points:

• Supporting angular.json as-is enables users to run Angular CLI directly
  • It would allow running some Angular CLI commands not available in Nx
  • It reduces the changes when converting to an Nx workspace
• There is a preference for configuration files per project (project.json) vs a single angular.json at the root
  • Fewer merge conflicts
  • Project configuration is co-located with the project code
  • Cache is not invalidated by changes to other project configurations

Overall, there's a strong sentiment about continuing to use project.json files vs a single angular.json file. The general reaction from existing Nx users is that they wouldn't go back to a single angular.json file at the root. Moving to a configuration per project was a major feature request back in the day and when it was introduced, there was no negative reaction to it, quite the opposite.

There's also a sentiment that it could be useful in some cases to infer tasks from angular.json and let the user run the Angular CLI.

Angular Crystal Plugin

One of the main objectives of Project Crystal is to ease onboarding. The main idea is to rely on the configuration files of third-party tools to infer the tasks to run for any given project. This reduces the Nx-specific configuration and leads to an easier adoption of Nx.

Angular it's a bit special. The Nx configuration and the Angular CLI configuration are pretty similar. This means that using the Nx configuration style for Angular is not too far off the Angular CLI configuration, and users learn it pretty quickly. The main differences are small and easy to learn. Our automated conversion (nx init) handles it for users. There's a general consensus that using configuration files per project is better than a single configuration file for all projects. Therefore, the onboarding of Angular users doesn't have the same challenges as a React, Vue or any other framework user, where their tooling and configuration are completely different.

The following are some pros and cons when it comes to supporting angular.json over project.json:

Pros:

• Users would continue to use the exact configuration they used for Angular CLI
• Users would be able to run Angular CLI commands

Cons:

• A single configuration file for all projects is harder to maintain, with increased chances of merge conflicts and disconnected from the project locations
• The cache for all Angular projects would be invalidated by changes to angular.json. While we could potentially look into solving this, it's a significant effort.
• Users wouldn't be able to set targetDefaults for specific executors. They can still set it for targets, but some targets use different executors. A workaround would be to having to rename targets to ensure each of them uses the same executor.
• Current Nx generators (from official and community plugins) will break. While we can update the official ones and provide some guidance/helpers to community plugins, it's a significant effort.
  • Given we'd still need to support projects fully defined in project.json files, the generators get more complex because they need to handle more scenarios.

Having said that, while supporting angular.json eases a bit the onboarding and allows running the Angular CLI, we don't think there's a significant improvement/benefit or that there's a major issue when it comes to onboarding Angular users. The added complexity and effort to maintain full support for angular.json (generators => schematics, executors => builders, custom hashing) is significant for the added value.

nx import

We're planning to help users onboard external repositories into an existing Nx workspace. We believe this is an exciting feature for a set of users that it's more feasible to implement thanks to Project Crystal.

One of the main goals when importing an external repo to an existing Nx workspace is to initially move the repository to an isolated directory within the workspace and avoid making any changes. The idea is that the users would be able to continue to run things the same way they did before, treating that directory as their root. Co-locating the external repository into the existing workspace is the first step, and being able to continue to run their tasks is a key aspect. Importing an external Angular CLI repository and using the Angular Crystal plugin would allow for keeping the configuration intact, while allowing them to continue to run the exact same tooling.

The following repo contains a POC where a simplified version of the plugin was implemented to showcase the experience of an imported repo with the Angular Crystal plugin: https://github.com/leosvelperez/nx-angular-crystal.

Note

Let's keep the discussion focused on the Angular Crystal plugin and not on the nx import functionality. That's a separate topic.

[Jordan-Hall]

Nicely summarised. Am I missing something in the demo repo. If your using nx import your keeping angular.json? Your example repo doesn't have this file though?

Also it be nice if nx import supports project.json too (I'll wait for tasked on this) but never all sounds good it will will help ngx maintenance project as we currently importing angular.json projects into nx

[leosvelperez]

@Jordan-Hall it's on a branch and under the directory where the external repo is imported. See https://github.com/leosvelperez/nx-angular-crystal/blob/imported-angular-cli-repo/projects/my-ng-app/angular.json.