Inconsistent Behavior of @schematics/angular With/Without @nx/angular

[Char2sGu]

Current Behavior

I am migrating a Angular CLI monorepo library collection project to NX. I decided to keep using @schematics/angular and thus removed @nx/angular because it is too opinionated and introduces too many things that I do not need. The workspace works mostly good, except of when generating new libraries:

When generating a new library (or application) with nx g @schematics/angular:library, the project.json configuration of all my other libraries are all unexpectedly updated, with all the inferred targets and targetDefaults options mandatorily added into the project.json files.

The output of the command does not show updates on the project.json files:

But they're indeed modified:

However, when trying to reproducing this issue within a new repository generated with Angular CLI and then migrated to Nx, everything worked as expected. I eventually figured out that it caused by the removal of the @nx/angular package. Once the @nx/angular package is installed back, the project.json files stay intacted when generating new libraries/applications with @schematics/angular.

Expected Behavior

Nx does not have a direct dependency on @nx/angular, and also the documentation did not mention that @nx/angular have to be installed to use @schematics/angular. Therefore, I believe the behavior of @schematics/angular should remain consistent with or without @nx/angular, which is that project.json files should not be mandatorily updated.

One other thing that I am quite confused about is that why the Nx generators force the installation of so many dev dependencies that seems extraneous to me.
Examples:

• when migrating an Angular CLI project to Nx, @angular-devkit/{core,schematics} and @nx/workspace are added, but I don't see any usage of these dependencies.
• when generating a library with @nx/angular, mandatorily installed dependencies include postcss, postcss-url, autoprefixer, @swc/{core,helpers}, @swc-node/register, @angular-devkit/{core,schematics}, and even @angular/language-service?? I can't find any direct or indirect usage of these dependencies, and was quite annoyed by their repetitive occurrence.
  If they're somehow used in the plugins, I expect to at least read about their importance in the plugin documentation. I would like to get a clearification on this too.

GitHub Repo

https://github.com/TheNightmareX/nx-angular-schematics-demo

Steps to Reproduce

1. npm install
2. npm run reproduce
3. Check projects/ng-cli-lib/project.json, and you'll find it unexpectedly updated

Nx Report

Node   : 18.19.0
OS     : linux-x64
npm    : 10.2.3

nx (global)    : 18.1.1
nx             : 18.1.1
@nx/workspace  : 18.1.1
@nx/devkit     : 18.1.1
@nrwl/tao      : 18.1.1
typescript     : 5.4.3

Failure Logs

No response

Package Manager Version

No response

Operating System

• macOS
• Linux
• Windows
• Other (Please specify)

Additional Information

OS: WSL2 - Ubuntu

[leosvelperez]

Thanks for reporting this!

Currently, the @nx/angular package is required by Nx to support Angular. Angular support is a bit special in Nx because Angular CLI schematics and builders require an angular.json file, but you don't have that file in an Nx workspace. Due to that, there's some special handling that's done, and it's only enabled when the @nx/angular plugin is installed. So, even if you don't want to use any of the @nx/angular generators or executors, you should install the package. Installing it doesn't mean that you need to use it directly. This is why our automated migration (nx init) installs it. We're planning to do some work in this area, so we might improve this in the future. For now, please keep the @nx/angular package installed to get the best experience.

Regarding the "unexpected" dependencies added by the generators, some of them are actually required by the @nx/angular package functionalities:

• @angular-devkit/{core,schematics}: are required to support running Angular CLI schematics and builders. Note in Angular CLI workspaces these dependencies are also used, but they are pulled as transitive dependencies of the @angular/cli package. The @nx/angular plugin doesn't use the @angular/cli package directly, but rather its building blocks.
• @swc/{core,helpers}, @swc-node/register: used by all JS/TS Nx plugins to load .ts configuration files in-process (e.g. webpack.config.ts)
• postcss, postcss-url, autoprefixer: used by the ng-packagr executors to support Tailwind CSS
  • There's room for improvement here. We could choose to add them only when adding Tailwind CSS and error if you try to use it and it's not installed.
• @angular/language-service: definitely not needed. We'll amend this.

Thanks for bringing it up and for being explicit about the things you think are wrong. There are some things that are immediately actionable, and we'll work on them.

Also, note that you can provide the --skipPackageJson flag to the generators, and they won't add any dependency. If you think you're good with the dependencies you have installed, or you want to manage them manually, you can provide that flag.

[Char2sGu]

Thank you very much for the detailed response!

I understand that currently the precense of @nx/angular is used to determine whether Angular support is enabled, but it does not make sense to me to implicitly change Nx's behavior based on the existence of a plugin, which is especially confusing to me as people don't normally expect an "unused" dependency to be so impactful. If this is the only way to go, I believe this should be signifcantly emphasized in the documentation.

Besides, I think this is more likely a bug instead of some inconsistent behavior for the following reasons:

1. the document mentioned that Nx has native support for Angular schematics.
2. The schematics are successfully executed. It's just there are additional files updated.
3. it seems like the parsed and normalized configurations are incorrectly wrote back to the project.json files, which seems to be a behavior that shouldn't happen in any cases.

Thanks for your clearification on the dependencies. However I'm still confused about several points:

1. I have tried --skipPackageJson at the very beginning, but it is not respected, at least not for @nx/angular:library. The installed dependencies are reduced, but there are still a lot of dependencies added: @angular/language-service, @nx/js, @swc-node/register, and @swc/{core,helpers}.
2. If I understand it right, @angular-devkit/{core,schematics} are installed just because the @nx/angular plugin depends on them. I'm confused about why they are not listed as peerDependencies or @nx/angular. By donig so, when installing @nx/angular, the peer dependencies will be implicitly installed by npm if and only if there are no existing installations to use, ensuring that there are only one instance of @angular-devkit/{core,schematics} being used. It seems unncessary to add these dependencies to the user workspace package.json without any direct reference/usage from the user workspace.
3. Similarly, the swc dependencies are used by Nx plugins, not by the user workspace. I also wonder why they are not added as peer dependencies of the Nx plugins, which also ensures there are only single instances of each swc package to be used.
4. Same question applies to Nx's ng-packagr executors too. These dependencies are required by Nx's executors, not by the user workspace. Then why not add them as dependencies of Nx's executors?

Overall, my point is that a package should not be added as a dependency of the user workspace, if it is not directly referenced/used from the user workspace. I guess the reason Nx adds them as user dependencies is to make sure the same instance of the dependency is used by multiple plugins, but I believe peer dependencies can solve that too.

I would really appreciate a clearification on this. The extraneous dependencies have been especially annoying to me, and it disallows me to remove unused dependencies since I don't know which are implicitly used by Nx.

[Char2sGu]

Revise: They are already listed as peer dependencies. I'm confused why it is still required to add them as user workspace dependencies even though they will be installed by npm automatically.

However, it is not the most important point. The point is that --skipPackageJson doesn't work. With --skipPackageJson I wouldn't care about whether or what dependencies are installed.

In summary, I suspect that there are two bugs:

1. Angular schematics are not executed correctly when @nx/angular is not installed.
2. --skipPackageJson does not work for some @nx/angular generators.

I'll be happy to help if they are confirmed as bugs. Let me know if I can help with anything.

[leosvelperez]

Thanks again for the feedback! This is valuable to us. Please see below.

They are already listed as peer dependencies. I'm confused why it is still required to add them as user workspace dependencies even though they will be installed by npm automatically.

There are three reasons our generators install dependencies:

• To install dependencies of the user applications (e.g. @angular/core)
• To lazily install dependencies required by optional functionality (e.g. ng-packagr which is needed if you use buildable/publishable libraries)
• To ensure the package manager resolves them at the root of node_modules. We've had issues in the past with dependencies being hoisted nested to some packages, and a different version resolved at the root, which can cause issues when tryíng to resolve those deps.

1. Angular schematics are not executed correctly when @nx/angular is not installed.

Long story short, while the implementation is currently not the best and we'll look into change it when we have some time, the end result will still be the same: you need to install @nx/angular in order to use Angular.

Angular is a bit special because there are no angular.json in the workspace and Angular CLI schematics and builders can't work without it. So, we have an adapter layer where we convert the configuration between project.json and angular.json in memory. The current implementation is in a weird state as you discovered, where part of this is in the nx package and some bits are enabled by the presence of the @nx/angular package.

I agree the current implementation is weird/wrong because, as you stated, if you only have the nx package installed, you can still run Angular CLI schematics but it has issues handling the project configurations. This is an unfortunate implementation detail though. As mentioned above, even when we fix that implementation, the intended usage won't change. The core of Nx shouldn't run Angular CLI schematics and builders at all and it would require the presence of @nx/angular to enable the functionality. So, from users perspective, the usage remains the same: you need to install the @nx/angular package in order to use Angular.

This is why when creating a new workspace or using our automated conversion (nx init), the @nx/angular package is always installed. So, unless you manually edit/remove/opt-out of things our official generators generate, you shouldn't have any issues.

I agree with your suggestion that this should be clearly stated in the docs. We'll review the docs and amend as needed.

2. --skipPackageJson does not work for some @nx/angular generators.

Yeah, there was an issue with the @nx/angular:library generator that was fixed by #22608 and released in Nx 18.2.2. I saw from your nx report log that you're on 18.1.1. Please migrate to the latest version to get the fix.

[Char2sGu]

Thanks for your response! It is very helpful!

---

There are three reasons our generators install dependencies:

I do agree that generators should add dependencies, and also agree with your first two points.

For the third point:

We've had issues in the past with dependencies being hoisted nested to some packages, and a different version resolved at the root, which can cause issues when tryíng to resolve those deps.

I totally understand that you have experienced such issue before, and figured that the solution is to install the peer dependencies at the root. However, I believe this issue no longer exists with the current peer dependency resolution strategy.

If @angular-devkit/schematics is listed as a peer dependency of @nx/angular, and @nx/angular is installed at the root, NPM will make sure that there will be one and only one matched version of @angular-devkit/schematics installed at the root, and will throw an error if this requirement cannot be met:

• If the user have already installed a version of @angular-devkit/schematics, NPM will try to use the installed version, and throw an error if the installed version does not meet the requirement.
• If the user haven't installed @angular-devkit/schematics, NPM will automatically install a valid version.

My proposal is that Nx generators should add ONLY direct dependencies that will be directly referenced/used from the user workspace, and should NOT add dependencies of dependencies to the user workspace, such as @swc/* and @angular-devkit/schematics. They are dependencies of the Nx plugins, not dependencies of the user's project, so I don't find a reason to add them to the user's package.json when it is already guranteed by NPM that a valid version of them will be available at the root.

---

The core of Nx shouldn't run Angular CLI schematics and builders at all and it would require the presence of @nx/angular to enable the functionality.

I am confused. Does it mean the current support for Angular schematics without @nx/angular is intended to be removed? I think the documentation keeps converying the idea that Nx has inherent support for Angular schematics.

Before we discuss the schematics support in Nx, I need to first point out that using packages implicitly (require the presence of a package) seems to be a bad design to me. If a package is used, the package name should be somehow referenced (unless it is an optional peer dependency that doesn't affect the package's behavior unless explicitly configured).

In order to distinguish and remove extraneous dependencies, developers usually perform a global search of the package name, and can tell a package being extraneous if no references to the package is found. However, as Nx is implicitly using a lot of packages without listing their names, developers can no longer tell which package is extraneous and which is not, since they'll never know what is needed by Nx and what is not, without looking into the source of each Nx plugin.

This also applies to how Nx currently automatically discover generators/plugins from node_modules. In order to enable a plugin, it should be explicitly listed in the plugins field of nx.json. It is somehow acceptable since all the plugins start with @nx/ and is easy to distinguish, but I would still request a change to avoid implicitly using packages.

Back to the topic of Angular schematics support in Nx.

First of all, I think the support for Angular schematics should be an inseparable part of Nx's core functionalities. Angular schematics are actually designed to be framework-agnostic at first, which is why they use @schematics/angular instead of @angular/schematics. We could regard the schematics as an alternative authoring format of generators, instead of seeing them as specialized support for Angular framework alone. This could be a good reason to have built-in support for schematics.

If you really decide to separate the support of schematics, I have another proposal:

Extract the schematics support from @nx/angular to @nx/schematics, and list @nx/schematics as an optional peer dependency of nx. When schematics: true is configured in nx.json, Nx loads @nx/schematics for schematics support and throw an error if the package is not found. An important point here is that Nx should never even attempt to load @nx/schematics without schematics: true being explicitly configured. I insist that it is an anti-pattern to implicitly try to load packages and determine the behavior based on whether a package is successfully loaded.

---

There was an issue with the @nx/angular:library generator that was fixed by #22608 and released in Nx 18.2.2.

I have migrated to latest, the current behavior is like this:

• less packages were installed: now only @angular-devkit/schematics and @angular/language-service
• my workspaces declaration was re-formatted
• the dependencies field was added as an empty object: {}.

By looking at its name, I expect --skipPackageJson to competely forbid the generator from writing a single byte to package.json. Please let me know if this is the expected behavior, or is it still a bug?

nx report result

Node   : 18.19.0
OS     : linux-x64
npm    : 10.2.3

nx (global)    : 18.1.1
nx             : 18.2.3
@nx/js         : 18.2.3
@nx/linter     : 18.2.3
@nx/eslint     : 18.2.3
@nx/workspace  : 18.2.3
@nx/angular    : 18.2.3
@nx/devkit     : 18.2.3
@nrwl/tao      : 18.2.3
@nx/web        : 18.2.3
@nx/webpack    : 18.2.3
typescript     : 5.3.3

---

Nx is a great project that I hope to make better, thus a lot of proposals are made in this comment:

1. Add only direct dependenceis to user workspace, i.e. do not install dependencies of Nx plugins to user workspace
2. Avoid automatically looking for plugins from node_modules. Instead, list the plugins explicitly in nx.json
3. Two proposals of schematics support: integrated or @nx/schematics
4. Question regarding --skipPackageJson behavior

Look forward to your response!

[leosvelperez]

If @angular-devkit/schematics is listed as a peer dependency of @nx/angular, and @nx/angular is installed at the root, NPM will make sure that there will be one and only one matched version of @angular-devkit/schematics installed at the root, and will throw an error if this requirement cannot be met

Ideally, yes. In practice, a lot of folks end up running npm i --legacy-peer-deps or npm i --force to bypass issues with conflicting peer dependencies. While we can talk about whether that's wrong and it's on them, the reality is that they do it and sometimes there are valid reasons to do so. Regardless of the reasons, it works for them, and our generators try to ensure that everything continues to work regardless of the scenario. When bypassing the peer deps requirement checks, you can end up with a different version of the peer dependency package resolved at the root and that causes issues due to different versions of the Angular DevKit. It normally happens when folks use older libraries that depend on older versions of the Angular DevKit.

I understand your reasoning, and it's not wrong. I'm not saying otherwise, but one thing to keep in mind is that our generators (like any code-generation tool out there) are opinionated. We're trying to make sure what we generate works in most scenarios. That's what we believe is the best to cover a broader range of setups. There's always going to be things we generate in a way that folks might agree or not. The beauty of Nx is that it's highly extensible, so you can create your own generators that better fit your conventions or preferences.

As mentioned before, the escape hatch for this particular issue is to run the generators with --skipPackageJson. Regarding that flag:

I have migrated to latest, the current behavior is like this:

• less packages were installed: now only @angular-devkit/schematics and @angular/language-service
• my workspaces declaration was re-formatted
• the dependencies field was added as an empty object: {}.

By looking at its name, I expect --skipPackageJson to competely forbid the generator from writing a single byte to package.json. Please let me know if this is the expected behavior, or is it still a bug?

You uncovered another issue, which I addressed on #22777. We released the change in Nx 18.3.0. Could you please try again with the latest version and let me know if it works? 🙏🏻

I am confused. Does it mean the current support for Angular schematics without @nx/angular is intended to be removed? I think the documentation keeps converying the idea that Nx has inherent support for Angular schematics.

That's correct. The core of Nx should only know how to run generators and executors written with the Nx DevKit. Running other tool artifacts (e.g., Angular DevKit schematics and builders) should be enabled by a plugin. The core of Nx is meant to be technology agnostic, and support for specific technologies (e.g., Angular DevKit) should be enabled by plugins. This is explained in our docs.

We can definitely be more explicit about it in the docs (I think I mentioned it already), but there's nothing in the docs explicitly stating that "Nx Core" supports Angular schematics. There's also nothing explicitly stating that a specific plugin is needed for it. So, we'll make sure to improve that.

Before we discuss the schematics support in Nx, I need to first point out that using packages implicitly (require the presence of a package) seems to be a bad design to me. If a package is used, the package name should be somehow referenced (unless it is an optional peer dependency that doesn't affect the package's behavior unless explicitly configured).

In order to distinguish and remove extraneous dependencies, developers usually perform a global search of the package name, and can tell a package being extraneous if no references to the package is found. However, as Nx is implicitly using a lot of packages without listing their names, developers can no longer tell which package is extraneous and which is not, since they'll never know what is needed by Nx and what is not, without looking into the source of each Nx plugin.

This also applies to how Nx currently automatically discover generators/plugins from node_modules. In order to enable a plugin, it should be explicitly listed in the plugins field of nx.json. It is somehow acceptable since all the plugins start with @nx/ and is easy to distinguish, but I would still request a change to avoid implicitly using packages.

I can see your point about the explicitness of registering a plugin, though I think it's a gray area. We've internally evaluated this in the past and decided on simplicity and less configuration. It's very common in plugin architecture to enable things by adding/installing plugins. You don't necessarily need to register them. For example, you don't register plugins in VSCode. You just install them, and they augment the VSCode core functionality.

A separate story is to want to control and be able to enable/disable functionalities. For example, you can enable/disable VSCode plugin functionalities through the options they expose to do so. Nx plugins don't currently offer a way to do so because we don't think it is needed for the most part:

• If you don't want to use generators, you just don't run the generator
  • Similarly, if you don't want to run an Angular DevKit schematic, you just don't try to run it
• If you don't want to use executors, you just don't set them in targets

Having to explicitly enable them in order to use them seems like an extra burden and configuration. Installing the plugin means you want to use its functionality. How much of its functionality you use is up to you.

Some things are effectively enabled/disabled through configuration (e.g., project graph plugins that infer tasks from tool configurations). That's the case with features that change Nx core behavior. You have the option to enable/disable them.

First of all, I think the support for Angular schematics should be an inseparable part of Nx's core functionalities. Angular schematics are actually designed to be framework-agnostic at first, which is why they use @schematics/angular instead of @angular/schematics. We could regard the schematics as an alternative authoring format of generators, instead of seeing them as specialized support for Angular framework alone. This could be a good reason to have built-in support for schematics.

We have to disagree here. The Angular DevKit (what powers the schematics) is not the same as the Nx DevKit. Nx is not tied to Angular in any sense (it used to be that way when it started as an Angular extension, but that hasn't been the case for a long time now). The fact you can use the Angular DevKit to write schematics for any tool doesn't mean that Nx should support it out of the box. There are other technology-agnostic generation tools out there, and that doesn't mean the core of Nx must support them. Looking at https://nx.dev/getting-started/why-nx#how-does-nx-work, the Code Generation box under Nx core refers to generating code using the Nx DevKit, not any other code-generation tool.

Extract the schematics support from @nx/angular to @nx/schematics, and list @nx/schematics as an optional peer dependency of nx. When schematics: true is configured in nx.json, Nx loads @nx/schematics for schematics support and throw an error if the package is not found. An important point here is that Nx should never even attempt to load @nx/schematics without schematics: true being explicitly configured. I insist that it is an anti-pattern to implicitly try to load packages and determine the behavior based on whether a package is successfully loaded.

The final package where we plan to move the Angular DevKit support is TBD. I mentioned @nx/angular just because it is the current implementation and to simplify the discussion. In reality, I agree it will be a different package. Once we re-work the Angular DevKit support (I previously mentioned we had already plans to do so), you'll either get an error when the required plugin is not installed, or you'll be able to successfully run Angular DevKit schematics.

As explained before, we have different opinions about needing to explicitly register plugins to use generators or other capabilities. We don't plan to do that any time soon.

[leosvelperez]

I want to separate bugs that we need to address from feature requests that we need to discuss more. To that extent, I want to focus this issue on the wrong behavior of --skipPackageJson.

Could you please retry running the generators with --skipPackageJson using the latest Nx version (18.3.0) and let me know if the issue is addressed? 🙏🏻

I'd be happy to continue the rest of the discussion on a separate GH Discussion. Any and all feedback is welcome to try to improve the tool. Please, create a separate GH Discussion (or multiple if you feel like it) to discuss the rest of the features we've discussed here (or others) you'd like Nx to support. You can of course link back to this issue if you need to reference anything.

[Char2sGu]

Hey @leosvelperez I appreciate the the update!
--skipPackageJson works well in 18.3.0. Thanks for the efforts.

I'd like to keep this issue open until Angular schematics support are completely extracted, or this behavior is expliclty documented.

[Char2sGu]

I see why Nx installs the dev deps by default, as long as --skipPackageJson works. It makes sure the updated workspace is functional by default, and allows adjusting dependency details. A step further is to output the skipped packages when --skipPackageJson is supplied, which can serve as a reference for developers who want to fine-tune the dependencies.

Speaking of explicitly listing plugins, I do agree that the current approach is pretty convenient, and I myself is not even sure what could be a better design, so no feature requests on that.

However, I do think it could be a good idea to allow the developer to explicitly list all the plugins that they want to nx to discover generators from. I prefer to use the shorthands such as nx g lib instead of nx g @schematics/angular:lib. However, in many cases, such a shorthand can be registered by multiple plugins in the workspace, such as @nx/js:lib, @schematics/angular:lib, and @nx/angular:lib, so I have to either type the full path of the generator or perform a follow-up selection, which seems quite verbose to me.

A proposal is to have an optional generatorsFrom property in nx.json. When specified, Nx will discover generators only from the specified packages:

"generatorsFrom": "@schematics/angular"

Finally, I would strongly recommend to have a separated package for schematics support, unless the previous generatorsFrom proposal is implemented. My initial motivation to remove @nx/angular is that I wanted to use nx g c instead of nx g @schematics/angular:c. By separating the schematics support into a dedicated package, developers are enabled to keep a similar CLI generating experience when migrated from Angular CLI.

I'll create dedicated issues for each of the feature requests above, but I'm not sure if the Nx team would like a public discussion for Angular schematics, and I think the Nx team should creates such a discussion.

[leosvelperez]

--skipPackageJson works well in 18.3.0. Thanks for the efforts.

Thanks for confirming! I created a PR to update our documentation by explicitly mentioning in a few places that the @nx/angular plugin is required to enable support for Angular DevKit schematics.

---

Once again, thanks for all the feedback! As advised before, please feel free to create Feature Requests (GH Discussions) for any new feature or behavior you think Nx should support. You don't need to wait for the team to create a discussion on anything you think should be discussed. Try to keep each feature request focused on a single feature to improve the discussion around it.

[Char2sGu]

@leosvelperez Unsurprisingly, opening feature requests as GH Discussions won't receive any feedback, which is why I planned to create tickets instead.

The following feature requests have been there for weeks. I don't know if the Nx team is even aware of their existences.

#22934
#22935
#22936

[github-actions]

This issue has been closed for more than 30 days. If this issue is still occuring, please open a new issue with more recent context.