RFC: Linking Packages with Workspaces (aka New TypeScript Setup)

[jaysoo]

Author: Jack Hsu
Published: 2024-11-27

Updated (2024-11-28): Add more information on how linking works, and how pnpm requires libraries to be specified as dependencies in package.json. Added the benefit of opting out of Single Version Policy in the intro. Added a note in intro that the old setup will continue to work even after this change.

---

This RFC proposes a transition from using tsconfig.base.json compilerOptions.paths for linking TypeScript packages to using the workspaces feature available in package managers like npm, yarn, pnpm, and bun. The transition also includes adding the @nx/js/typescript plugin to keep TypeScript project references in sync (via nx sync) and infer a typecheck target for all TypeScript projects.

We will focus on application development (both web and backend), and we are collecting feedback on the DX differences between the old (aka "integrated") and the new TypeScript monorepo setup.

The goal is to modernize our TypeScript monorepo setup, while retaining what makes Nx development great for application development. Some of benefits of the new setup include:

• Lowering the barrier of entry for new Nx users by relying on common standards (workspaces, project references) rather than Nx-specific features.
• Making our generators more flexible so you don't have to conform to the old (aka "integrated") setup. You can nx init into most existing workspaces and use @nx/react and other plugins.
• Allowing local tsconfig paths, such as @/ to be used in each application. This is popular in Next.js and Remix projects.
• Allowing multiple versions of the same package to be used for different projects within the monorepo (i.e. opting out of Single Version Policy). This is especially useful for legacy systems, and to enable incremental migrations to new React/Angular/etc. versions.
• Fixing long-standing issues with references not being found (particular in VSCode Cannot find all references to shared lib's interfaces in VS Code #3106).

The main impact will be for application developers that have buildable libraries used by their apps. There will no longer be an option to bundle buildable libraries from source.

Also, note that the old setup will continue to work. Our generators will continue to support tsconfig paths, so there isn't a need to migrate to the new setup if the old one works well for you.

Terminology

• Workspaces - the feature provided by all support package managers (npm, yarn, pnpm, bun) to manage multiple packages in the monorepo
• Old setup - linking packages via compilerOptions.paths in tsconfig.base.json, which is currently the default.
• New setup - linking packages with workspaces (npm, yarn, pnpm, bun), which is currently available via npx create-nx-workspace --preset=ts.
• Non-buildable library - a library that does not have a build target. Consumers of the library are projects within the monorepo.
• Buildable library - a library that has a build target and can be published to a registry. Consumers or the library can be within the monorepo and external to the monorepo.

Detailed Explanation

Current Setup

In the current monorepo, when you create a library such as the following:

npx create-nx-workspace acme --preset=react-monorepo
cd acme
npx nx g @nx/react:lib packages/foo

You will see an entry in tsconfig.base.json that maps @acme/foo to an internal path within the monorepo.

{
  "compilerOptions": {
    "paths": {
      "@acme/foo": ["packages/foo/src/index.ts"]
    }
  }
}

This allows TypeScript and bundlers to map imports from @acme/foo to their source. There are some downsides:

• Exports from package.json is not the only source of truth, and developers must add an entry to tsconfig.base.json as well to point to the correct source
• TypeScript cannot reliable find all references, particularly in VSCode (Cannot find all references to shared lib's interfaces in VS Code #3106)
• Developers cannot use the common @/ alias, popular in Next.js, Remix, etc. since the local paths completely overrides the ones from tsconfig.base.json.

Proposed Setup

We propose switching to the workspaces feature provided by package managers. This would involve:

1. Workspaces: Adding a workspaces field in package.json:

   {
     "workspaces": ["apps/**", "packages/**"]
   }

   or the equivalent configuration for other package managers like pnpm and bun.

2. Dependency Linking: The package manager will link libraries in the monorepo during install (e.g. npm install).

TypeScript and bundlers will resolve imports from @acme/foo using Node resolution rather than through compilerOptions.paths.

We'll also add @nx/js/typescript plugin to nx.json, which syncs project references and infers a tyepcheck target on TypeScript projects.

Feedback Requested

We are collecting feedback on:

• Clarity - is it clear what the new setup does, and why it will be the new default?
• Developer experience - does the new setup make sense to you? Are there any gaps we have not identified?
• Ease of transition - when you migrate from the old setup to the new setup, how high of an impact will there be to you and your teams? Particular for those that use buildable libraries.

Let's examine four development workflows :

1. Web applications that have dependencies to workspace libraries.
2. Web applications that have dependencies to buildable libraries.
3. Node applications that have dependencies to workspace libraries.
4. Node applications that have dependencies to buildable libraries.

And also look at two changes:

• How typechecks are performed in the new setup (i.e. not through builds but as a separate target).
• Changes to buildable libraries, how assets and dist are no longer copied to {workspaceRoot}/dist but remain in the projects root. This mostly affects published libraries.

Use-Case: Web Applications Using Non-Buildable Libraries

When generating libraries for web applications, we will default them to be non-buildable. More specifically, this refers to the following generators:

• @nx/react:library
• @nx/next:library
• @nx/remix:library
• @nx/expo:library
• @nx/react-native:library
• @nx/angular:library
• @nx/vue:library
• @nx/nuxt:library

We no longer generate a project.json, and instead a package.json will be added. For example, if you run nx g lib packages/foo then packages/foo/package.json looks as follows:

{
  "name": "@acme/foo",
  "nx": {
    "name": "foo",
    "projectType": "library",
    "sourceRoot": "packages/foo/src"
  },
  "main": "./src/index.ts",
  "types": "./src/index.ts"
}

Libraries no longer have the Nx-specific project.json file, and instead we have the package.json file that standard in JS projects. This could be a breaking change for custom generators that assume the existence of project.json, but can be mitigated through the use of project utils from @nx/devkit(e.g. updateProjectConfiguration).

After library is generated, Nx runs install (e.g. npm install) to update the workspace. For npm, yarn, and bun, the new package will be under the root node_modules/@acme/foo so Node resolution works. For pnpm, this is not the case, and we have two options to link the new package:

1. Add to the root package.json as devDependencies so the library will be under the root node_modules and available for applications to use.
2. User manually adds the library to the application's package.json (e.g. apps/demo/package.json) and runs pnpm install.

(1) is preferred to avoid the user having to manually update files before consumption of the new library. It is also technically incorrect to add the library to the application's package.json file since it will be bundled into the production output, thus not a dependency to run.

The main and types fields point to the source ./src/index.ts file. This means that both TypeScript and bundlers will resolve to the source file using Node resolution, and we no longer need tsconfig-paths or similar plugins for bundlers to resolve non-buildable libraries.

To add a deep import path (e.g. @acme/foo/deep), previously you would add to tsconfig.base.json:

{
  "compilerOptions": {
    "@acme/foo": ["packages/foo/src/index.ts"]
    "@acme/foo/*": ["packages/foo/src/*"]
  }
}

In the new setup, you add an exports field to package.json. This is a standard Node feature and follows Node resolution that is supported in all bundlers (and tsc). We encourage not using wildcards, and be explicit about public API like so:

{
  "exports": {
    "./package.json": "./package.json",
    "./deep": "./src/deep/index.ts"
  }
}

This means potentially more entries required for deep imports, but has the advantage of creating stronger module boundaries.

Note: There is a strict requirement for libraries to be non-buildable if you want both TypeScript and bundlers to refer to source. If you make the library buildable in the future, you will be forced into incremental builds, as we'll cover in the next section.

Before you can commit and push your branch, you'll need to run nx sync so Nx can update the application's references (e.g. apps/demo/tsconfig.json). Otherwise, CI will fail on typecheck. This reference will also be updated when you run build or typecheck targets for any project.

There are two options to avoid running nx sync manually:

1. Add postinstall script to nx sync, which will happen when the new non-buildable library is generated.
2. Run nx sync after library generator is done, as a GeneratorCallback.

(2) is preferred so we don't need additional package scripts.

Use-Case: Web Applications Using Buildable Libraries (e.g. Incremental Builds)

This affected generators are the same as the previous non-buildable section:

• @nx/react:library
• @nx/next:library
• @nx/remix:library
• @nx/expo:library
• @nx/react-native:library
• @nx/angular:library
• @nx/vue:library
• @nx/nuxt:library

Also note that the generic @nx/js:library generator will continue to default to creating buildable libraries. Thus, anyone who is used to running nx @nx/js:libraryneeds to none when prompted for bundler, or pass --bundler=none to the generator in order to avoid incremental builds.

We will no longer generate project.json, and will continue to generate a package.json for the library with the additional nx field to mark it as an Nx-project. For example, nx g lib packages/foo creates packages/foo/package.json as follows:

{
  "name": "@acme/foo",
  "nx": {
    "name": "foo",
    "projectType": "library",
    "sourceRoot": "packages/foo/src"
  },
  "exports": { ... }
  "types": "./dist/index.d.ts",
  "main": "./dist/index.js"
}

Just like non-buildable libraries, Nx runs install (e.g. npm install) to update the workspace. For npm, yarn, bun, the new library is linked in the root node_modules and is available for consumption. For pnpm, we have the same two options as non-buildable libraries:

1. Nx adds library to the root package.json's devDependencies so the library exists in the root node_modules.
2. User manually adds to the application's package.json file and runs pnpm install again.

Same as the previous section, we're leaning towards (1) for the best DX.

In this setup, there will be a build target for the library, and developers must build the library prior to consumption by the application.

That means if you have an application at apps/demo with app component (apps/demo/src/app.tsx) like so:

import { Foo } from "@acme/foo";
export function App() {
  return <Foo />;
}

Then before serving the app, you must also run nx build foo or else you will get an error that packages/foo/dist/index.js does not exist, which is the main entry as defined in packages/foo/package.json.

We have a few options to help alleviate this pain point:

1. Add ^build to the serve target's dependsOn inside apps/demo/package.json, which means that serve will never error out due to missing dist. This will need to be configured for each app, so could lead to duplicated configs.
2. Add ^build to the targetDefaults of serve in nx.json, which means all serves will run build of their dependencies. This means we may apply dependsOn for projects that does not need it.
3. Do nothing, and rely on developers to run build of the libraries before serving the app.

(3) is consistent with non-Nx monorepo setup, but we're leaning towards (1) so all targets work out of the box, but we keep the config scoped to the projects that need it. The infinite task / sidecar RFCs (linked at the bottom) could be an option as well when they land.

Note that we will not watch changes to the library, so users will need to run the library build in order for changes to reflect in the application. For example,

1. User runs nx serve demo, which will run nx build foo (and build for other deps) first, then start dev server.
2. User updates packages/foo/src/index.ts
3. Application does not reflect the library changes.
4. User runs nx build foo.
5. Application is updated and either live-reloads or HMR (whichever is supported).

The same requirement to run install and nx sync exist as the first use-case.

Use-Case: Node Applications Using Non-Buildable Libraries

This workflow is for the following generators:

• @nx/js:library
• @nx/node:library

The @nx/js:library generator currently generates a buildable library by default, whereas @nx/js:node generates a non-buildable library. In order to ensure users get the best experience as possible, we will change @nx/js:library to create non-buildable libraries by default as well.

In this case, if your application is using a bundler (e.g. esbuild, webpack), then we will continue to support bundling in non-buildable libraries. However, if you transpile using tsc or swcthen you must use buildable libraries and have to use incremental builds (as covered in the next section), and we will not provide any solution to import non-buildable libraries with tsc. The requirement to use buildable libraries for tsc and swc is different from web applications, where all bundlers will support building from source.

We no longer generate a project.json, and instead the configuration goes under an nx entry in package.json. If you have a custom generator that assumes project.json then you will need to update it to use project utils from @nx/devkit. Deep imports are handled the same way as non-buildable libraries for the web. For example, if you run nx g lib packages/util then the package.json may look as follows with deep imports:

{
  "name": "@acme/util",
  "nx": {
    "name": "util",
    "projectType": "library",
    "sourceRoot": "packages/util/src"
  },
  "exports": {
    "./package.json": "./package.json",
    "./deep": "./src/deep/index.ts"
  },
  "main": "./src/index.ts",
  "types": "./src/index.ts"
}

The exports are encouraged to be more specific rather than using a wildcard compared to the old setup (e.g. "@acme/util/*": "packages/util/src/*" in compilerOptions.paths). This enables stricter module boundaries for the public API.

The same requirement to run install and nx sync exist as the first use-case (web application with non-buildable libraries). Nx could run both automatically as a GeneratorCallback.

Use-Case: Node Applications Using Buildable Libraries (Incremental Builds)

This workflow is for the following generators:

• @nx/js:library
• @nx/node:library

The generators will not create buildable libraries by default so users have to opt in. Similar to web applications, buildable libraries only works with incremental builds. There is no longer an option to build libraries from source, unless you choose non-buildable libraries (previous section).

Note: as mentioned in the previous section, @nx/js:library will no longer generate buildable libraries by default. You will need to choose a bundler other than none to make it buildable.

The initial serve will fail if dependencies are not built. So if the user has an application and library generated as follows:

nx g @nx/node:application apps/api --framework express
nx g @nx/node:library packages/util --bundler tsc --importPath @acme/util

And then consumes @acme/util from apps/api/src/main.ts as follows:

import { util } from "@acme/util";
console.log(util());

// ...

Then, before serving the API, you need to run nx build util first. The same options as web applications exist to improve this experience:

1. Add ^build to the serve target's dependsOn inside apps/demo/package.json, which means that serve will never error out due to missing dist. This will need to be configured for each app, so could lead to duplicated configs.
2. Add ^build to the targetDefaults of serve in nx.json, which means all serves will run build of their dependencies. This means we may apply dependsOn for projects that does not need it.
3. Do nothing, and rely on developers to run build of the libraries before serving the app.

Again, we are leaning towards (1) for now. The infinite task / sidecar RFCs (linked at the bottom) could be an option as well when they land.

That means, the initial serve works, but subsequent changes to the buildable libraries are not watched.

1. User runs nx serve api, which will run nx build util (and build for other deps) first, then start API.
2. User updates packages/util/src/index.ts
3. Application does not reflect the library changes.
4. User runs nx build util.
5. Application is updated and server is reloaded if watch: true (@nx/js:node executor option) for the serve target. Otherwise, you must kill and restart the server.

Also note that project.json will not be created for the application and library. Instead, a nx entry is added to the package.json file to provide Nx configuration. Again, this could have implications on custom generators that assume existence of project.json file. The library's package.json will point to the build artifacts, just as they do for buildable web libraries.

{
  "name": "@acme/util",
  "nx": {
    "name": "util",
    "projectType": "library",
    "sourceRoot": "packages/util/src"
  },
  "exports": {...}
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

The same requirement to run install and nx sync exist as the first use-case (web application with non-buildable libraries). Nx could run both automatically as a GeneratorCallback.

Use-Case: Typechecks

In the new setup, the @nx/js/typescript plugin infers typecheck targets for all included TypeScript projects. This means that typechecks can happen in two places:

1. When nx run-many -t typecheck is run
2. When nx run-many -t build is run (assuming the underlying tool, such as Webpack/Rspack, is configured to typecheck)

In the old setup, builds perform typechecks by default, since we don't a separate typecheck target for every project. In the new setup, we want to update application and library generators for the following stacks such at builds no longer do typechecking by default:

• Angular
• React (including Next.js, Remix, React Native, Expo)
• Vue (including Nuxt)
• Node (including Express, Fastify, NestJS, Koa)

If you rely on build in CI to also typecheck, then this will no longer be the case. Instead, CI scripts should also include typecheck target.

Note: This will affect nx g ci-workflow since we should also include typecheck by default.

Use-Case: Published Libraries and Output Files

In the old setup, we always point the output folder for build to {workspaceRoot}/dist by default. This setup also came with asset management, like generating/copying package.json and README.md` files to the output folder.

In the new setup, the dist folder is moved to within the project root. This is required to allow linking to work via workspaces. Thus, after a build you will have something like this:

packages/util
├── dist
│   ├── index.d.ts
│   ├── index.js
│   ├── index.mjs
│   └── lib
│       └── util.d.ts
├── src
│   ├── index.ts
│   └── lib
│       └── util.ts
├── package.json
├── README.md
├── tsconfig.json
└── tsconfig.lib.json

The contents of the source package.json must in a publishable state. That is, correct version, files, etc. There is no asset management via generatePackageJson or assets options like in the old setup. You are expected to ensure that the project root contains all the publishable artifacts.

Timeline

1. RFC Discussion Period: We will keep this RFC open for discussion until December 31st, 2024.
2. Implementation: We're planning to land the new setup for all official stacks (React, Angular, Vue, Node.js backend) by mid-January 2025.

How to Provide Feedback

Please provide your feedback by commenting on this RFC directly. If needed we can spin up additional discussions from the comments.

Other resources

• Infinite Tasks RFC: RFC: Infinite Tasks #29025

[lppedd]

I'd like to check out my use case (graph is trimmed down for clarity).

Currently, fa-vscode's package.json does not declare any dependencies to those shared libraries, and I don't have to run npm install every time I create a new library, as everything is resolved through tsconfig path aliases.

fa-vscode's project.json declares two main targets:

// Optimal for debugging & used by all shared libraries
"build": {
  "executor": "@nx/js:tsc",
  ...
},
// Used for bundling and publishing
"bundle": {
  "executor": "@nx/esbuild:esbuild",
  ...
}

When I want to launch a debug session, I simply forward a nx run fa-vscode:build, which compiles all libraries' TS files (incrementally).

Now correct me if I'm wrong, with the new setup I'll have to:

1. Create a package.json for all buildable shared libraries + remove their project.json files (?)
2. Add those buildable libraries as npm workspace packages
3. Link those buildable libraries in fa-vscode's dependencies, and between themselves

Will I still be able to simply run nx run fa-vscode:build to compile my TS sources?
And what about the buildable and publishable package? Will I still be able to have a custom publish target that runs build and publishes to the npm registry?

Note that personally, the separation between package.json and project.json is nice. I don't really like mixing a standard with tool-specific stuff.

[jaysoo]

1. We'll generate only package.json files by default, but project.json will remain supported by Nx itself. If you prefer the latter, then having a customer generator may be the way to go.
2. Correct, this is needed when tsconfig paths are not used.
3. Yes and no, for npm/yarn/bun the libraries (buildable or not) are linked in the root node_modules, thus Node resolution works even if they aren't added as dependenciesin anypackage.json. For pnpm, there is an option of adding the libraries to the root package.jsonasdevDependenciesto avoid having to include them in individual project'spackage.json` file.

[lppedd]

Re point 3. I guess the most correct way would be to link them tho, to avoid bad surprises in the future, right?

Will I still be able to simply run nx run fa-vscode:build to compile my TS sources?
And what about the buildable and publishable package? Will I still be able to have a custom publish target that runs build and publishes to the npm registry?

And I guess since project.json is going to be supported anyway, the answer is yes.

[lppedd]

However I still don't get how

There will no longer be an option to build buildable libraries from source

can relate to a project.json with a build target. Why wouldn't that work?

[jaysoo]

For buildable libraries, the package.json points main and other exports to the dist folder. For example:

{ 
  ...
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

This means that Node resolution will always point to dist rather than source. You could manually update them to point to source, but then the library itself cannot be published to a registry since in that scenario it should not point to source.

[beaussan]

First of all, I love this RFC, thanks a lot for the work you put into it!

In the past, I use to rely heavily on tsconfig path resolution, but in the last year I shifted to the approach you are mentioning (more specifically, Use-Case: Web Applications Using Buildable Libraries (e.g. Incremental Builds)).

One big feature you are not talking about is multiple version of third party. When working on legacy systems, using ts path resolution was always a huge challenge to align versions of third party, and the price to entry was huge. With this, it opens the door to more incremental adoption within a system.

However, the dependancy check rule from Nx eslint plugin is not working well since it assumes there is only one version of a given dependancy in the monorepo. With this change, this assumption is no longer applying

Having incremental build also allows for incremental migration where config are not uniform yet !

One question, do you think infinite tasks will land as a requirement of this new workspace linkage ? One of the biggest pain point we have is to have to spin up nx run <my-lib>:build --watch on a bunch of project manually to have some kind of live reload in the final app.

Lastly, regarding generating buildable libraries, especially with vite, are you considering adding a plugin such as vite-plugin-externalize-deps ? Currently, the generated vite config only exclude (for react) react, react-dom and the react runtime. However, if you are moving toward more incremental builds, with package.json references, without this plugin that means bundling every single dependancies on the project into the bundle. This could lead to issues like react context not properly linked and bundle size issues

Clarity - is it clear what the new setup does, and why it will be the new default?

This RFC is a great way to explain it yes. However, there might be some documentation missing around how the composite TS build works (maybe I missed it ?)

Developer experience - does the new setup make sense to you? Are there any gaps we have not identified?

Like mention, with infinite tasks, it solves a large part of the current DX drawbacks

Ease of transition - when you migrate from the old setup to the new setup, how high of an impact will there be to you and your teams? Particular for those that use buildable libraries.

This is something that is deeply missing, currently the only way to migrate to the new typescript setup is to generate a new workspace and figure out what makes it different. Having a guide (and maybe a generator in the future) is something that would be welcome!

Furthermore, this means changing for project:

• release management, since the dist lives in the project
• I assume things like coverage will live in the package folder too, and that means also changing coverage collection, etc

One last thought, I think this option should be enabled by default on package resolution monos:

{
  "pluginsConfig": {
    "@nx/js": {
      "projectsAffectedByDependencyUpdates": "auto"
    }
  }
}

On a integrated monorepo, an update on the lockfile only means "a third party was updated", however in package resolution, an update on a lockfile also mens "a internal package consumes an internal package update" given the dependancies of internal packages are also track in lockfiles, meaning that affected is wrongly behaving (treating lockfile as a global update) and thus, have worse caching performance

Overall, I think it's a great move to a more standard and less magic way of scaling monorepo

[jaysoo]

1. For @nx/dependency-checks we should definitely be expanding it to account for multiple versions. We already know about them from the lockfile. I'll make sure this is addressed.
2. I don't think Infinite Tasks will block us from moving forward with the changes in this RFC. I have discussed it with @FrozenPandaz on how it could resolve some painpoints related to incremental builds, but nothing concrete yet. I think nx watch -p <app> -d -- "npx nx build \$NX_PROJECT_NAME" kinda works for now, but we'll definitely be looking at enhancing the DX for incremental builds.
3. I made a note to take vite-plugin-externalize-deps or something similar into account. We did similar things for Rollup, so it's not crazy to support for this out of the box.
4. re: some documentation missing around how the composite TS build works -- The official docs on Project References is a good resource, but we'll also work on some docs on nx.dev to cover this topic.
5. re: This is something that is deeply missing, currently the only way to migrate to the new typescript setup is to... -- Yes, a recipe for the migration and potentially a generator is something we'll work on.
6. I like the idea of setting projectsAffectedByDependencyUpdates: auto if lockfile will have higher churn.

[yharaskrik]

This is fantastic! I love the idea of removing some of the magic, even if Nx is amazingly magical ;)

Couple of questions

Lib generation path for non-buildable libs

In the RFC you say this:

After library is generated, Nx runs install (e.g. npm install) to update the workspace. For npm, yarn, and bun, the new package will be under the root node_modules/@acme/foo so Node resolution works. For pnpm, this is not the case, and we have two options to link the new package:

But in the package.json directly above says: "sourceRoot": "packages/foo/src". Maybe I am not understanding what is being said but the first quote seems to be saying the package is generated into {workspaceRoot}/node_modules/@acme/foo. That can't be right, right? I would assume (as the package.json says) {projectRoot} is still within the checked-in bounds of the repo (in our repo its libs/ but the package.json has packages.

Could you clarify that a bit please and thank you? (Note: I have never used workspaces with any package manager so I may be missing a key piece of information here).

Migration path

I know its not explicitly mentioned but hoping that there is planned to be a migration path sometime close to the release of this feature? I don't want to get super excited on it but then not be able to migrate to it. I know you all said it is going to be pretty complex to migrate existing workspaces (ours was generated forever ago as you can probably tell by the libs/ folder) but hoping that it is being thought about and worked on so all of us can move to more standards based setups. I will happily run alpha migrations against our repo to help catch edge cases and all that if that would help!

Performance

It is obviously very early days, and I realize things will change and it will be hyper dependent on the repo and all that but whats the performance difference between compilerOptions.paths and Workspaces? I would suspect workspaces are quite a bit more performant but thats just from having some basic conversations prior to this.

Thank you all for the work on this RFC and special thanks to @jaysoo for writing it up, excited for the future!

[lppedd]

Also, will this RFC target a new major release? e.g. 21.0.x?
That would give people time to migrate, and potentially wait for bugs to be fixed, while also receiving important updates on the 20.x stream.

[yharaskrik]

Also, will this RFC target a new major release? e.g. 21.0.x? That would give people time to migrate, and potentially wait for bugs to be fixed, while also receiving important updates on the 20.x stream.

I would think they aren't just going to migrate everyone, both repo structures would be supported simultaneously.

[jaysoo]

Lib generation path for non-buildable libs

The sourceRoot in nx configuration does not affect how libraries are linked, it is purely there for Nx as we've noticed some generators don't work without this property. In the future we'd like to remove having to define sourceRoot as well, but I think that will be a future clean-up item.

In terms of libraries being linked in {workspaceRoot}/node_modules, this is correct. As long as your package.json specifies workspaces that includes the libraries (e.g. packages/**) then running npm install / yarn install / bun install will symlink libraries at the root. Pnpm is the exception here, and we should decide on the best between Nx automatically adding the dependency, or users manually adding them to the consuming applications.

Migration path

We'll release in phases:

1. create-nx-workspace defaults to old setup, but passing --workspaces will opt into the new setup. This is the testing phase to make sure we cover common workflows well.
2. create-nx-workspace defaults to the new setup, and passing --no-workspaces will opt out of it. We'll also provide a guide/ recipe on how to migrate existing workspaces manually + explain the new setup.
3. Provide a generator to convert old setup to the new one.

The work for (1) and (2) have already begun, and we're planning to land in early 2025 (we'll likely release with (1) in December 2024 which will make this opt-in). For (3), there is no current timeline, but it will be a fast follow.

[jaysoo]

Also, will this RFC target a new major release? e.g. 21.0.x?

In all likelihood this will land prior to v21, but there will be no need to migrate if the old setup is working fine for you. There will always be the option to go back to the old setup as well for create-nx-workspace (either through --no-workspaces, or we can even prompt for it).

[lppedd]

@jaysoo thanks! Worth writing it in the RFC, as it reads like an irreversible change (at least imo).

[edbzn]

The new setup is certainly more standardized, but it introduces additional complexity compared to the old one. For instance:

• Explicitly declaring dependencies in the project package.json.
• Running package manager commands to link packages.
• Synchronizing TypeScript references.
• Running typechecking as a separate step.

From a developer experience perspective, I’m not convinced it lowers the barrier for newcomers. However, I do believe it establishes a stronger foundation for large monorepos, offering better performance and more clearly defined project boundaries. Overall, it seems like a reasonable tradeoff.

That said, I have two main concerns:

1. Lack of incremental migration support
   This creates significant challenges for large monorepos, where a big-bang migration is often impractical. Could an incremental migration path be considered?

2. Divergence of styles
   Transitioning to the new setup might be difficult. What is the plan for maintaining compatibility with the old style? Will all plugins (e.g., Angular) fully support the new setup? I’m concerned about ending up with two divergent styles, with one eventually being abandoned. A clear migration plan would help teams prepare effectively.

Clear answers to these questions would greatly simplify the transition.

[jaysoo]

To address the first two bullet points (having to declare dependencies and running install), there should't be noticeable changes to DX assuming you are using non-buildable libraries. Package managers, except for pnpm, will link the non-buildable libraries in the root node_modules so they can be consumed without changes to package.json. For pnpm, we are looking at options to avoid having to declare dependencies. We can run install after generating a library, so you don't have to run it manually.

For buildable libraries, it should already be the case that package.json contains the buildable library. In the new setup, incremental builds will be required (i.e. building an app will consume buildable libraries from dist instead of source). Happy to hear more thoughts on this constraint.

---

Now, for the points on lack of incremental migration and divergence of style. We will provide guides on these. You could still use tsconfig paths to link older packages and incrementally migrate them. We'll also continue to support the older setup, so there is no need to migrate if it works well for you.

[danielsharvey]

Thanks for the RFC, it is detailed and very helpful.

I have a question regarding Angular: I've not seen the use of project references for Angular apps or libraries. From my look, it is not supported - see angular/angular#37276.

Do you have an approach in mind?

[jaysoo]

We are looking at it but don't have anything as of yet.

[ccaspanello]

This sounds promising ... PNPM has a concept of catalogs (https://pnpm.io/catalogs) would we be able to leverage this to help manage versions in one place and or incrementally upgrade frameworks like React ?

[jaysoo]

There shouldn't be anything preventing that usage for third-party packages (like react). For workspace libraries, I don't think we'll use it in our generators since we're sticking with features that work across package managers. That is, if there is enough demand for it we'll take a look.

[NachoVazquez]

This is an excellent effort going in the right direction (IMO). Thanks!

One question. In the past, via tspath, we were accustomed to creating a large import path for the entry point of a library. The folder structure often guided the convention for the library name, import path, and tags. However, by protocol, the package.json only supports one forward slash in the import path.

good: @acme/utils
bad: @acme/portal/auth/server/domain

How can we migrate to the workspace structure following the old conventions?

Example of previous conventions:

// located at packages/portal/auth/server/domain/src/index.ts
// with tags application:portal, subdomain:auth, technology:server, type:domain
import { ... } from '@acme/portal/auth/server/domain';

[yharaskrik]

One thing I'd like just a bit for clarity Jack.

Let's say we have these libs (Nx names)

shared-util-web-date
shared-util-web-layout

Where the project roots are:

libs/shared/util/web/(date|layout)

In this new setup would each of those have a package JSON in their project roots with name: @acme/shared and then each have their own exports:

util/web/date

And

util/web/layout

Is that valid since now there are two package jsons with the same name? (But don't actually have a main since they are really just exporting a secondary entry point to point the rest of the way to the project roots)

[NachoVazquez]

Here are some thoughts so far with the new workspace structure:

Existing Architectural guidelines are deprecated

The primary reason is that due to the import path limitations on npm packages, vertical and horizontal layers can no longer be created based on the folder structure.

A single package with multiple entry points is impossible when your vertical layers involve different technologies like Angular, React, Node, and IaC. Mixing these technologies could cause performance or incompatibility problems, as they are supposed to live separately.

Using different import scopes and disaggregated grouping folder structures moves you away from DDD and CCP/SRP patterns.

The Nx @nx/enforce-module-boundaries stop is worthwhile unless you need straightforward boundary enforcing or are looking for external import enforcing.

I understand this is not Nx's responsibility, but it breaks years of conventions and architectural designs.

Generators and Executors become less valid

Since your folder structure has become flatter and dependencies are specified in package.json, using generators and executors is arguably less important.

Instead of Nx generators, you could use boilerplate generators for specific technologies like other Monorepos. The counterargument would be keeping support for migrating libraries breaking changes like React, Angular, and ESLint automatically.

For executors, Nx has supported caching the npm scripts for some time. Now, executors don't need to know how to find the project dependencies since they are specified at the package.json level.

The counterargument may concern atomic executors used on agents for e2e tests, but this is only valid for users of Nx Cloud.

PD: If I made any error in this analysis, please let me know, and I will correct it.

• IaC (Infrastructure as Code)
• DDD (Domain Driven Design)
• CCP (Common Closure Principle)
• SRP (Single Responsibility Principle)

[yharaskrik]

What Nacho brought up is essentially my concern, we have been architecting our repo for years by following the guidelines laid out by Nx where we have the different types of libs (data access, util, feature, etc), different scopes (specific to our use case, globally shared, or within a certain app domain or something like that) and then platforms (server, web, any).

That means we have things like:

shared
- util
-- web
-- server
- data-access
-- web
--- <project1>
--- ....
-- server
--- <project2>
--- ....
- ...

etc. They get deeply nested (although no more than maybe like 4 levels deep). Since we can have a globally shared data access web library for example.

Or just a globally shared, util lib that any platform can use.

If we have been architecting this wrong the whole time by all means tell me but when we first started using Nx many years ago grouping and structuring based on the tags, types and scopes of libraries was the suggested practice. What I want to know is are we going to be able to use this new structure or not without major refactoring?

[beaussan]

Instead of Nx generators, you could use boilerplate generators for specific technologies like other Monorepos. The counterargument would be keeping support for migrating libraries breaking changes like React, Angular, and ESLint automatically.

Arent't already nx generators boilerplate generators ? I work on a monorepo using the workspaces reference for a year, and we couldn't make it work properly without generators. We are based on the one from nx but with a bit of tweaks to make them work for workspace based mono

For executors, Nx has supported caching the npm scripts for some time. Now, executors don't need to know how to find the project dependencies since they are specified at the package.json level.

For me, I see executors as a way to wrap more complex logic that you can't do as a simple npm command and a way to distribute them easily, and I think they are still useful.

Using different import scopes and disaggregated grouping folder structures moves you away from DDD and CCP/SRP patterns.

You could still have nested folders, you are not forced to have a single flat folder, however to have npm complient naming, you can't have a /

So, you can still have a folder structure of

libs
	domains
		shop
			data
				package.json#name => @acme/domains-shop-data
			ui 
				package.json#name => @acme/domains-shop-ui
			something-else
				utils 
					package.json#name => @acme/domains-shop-something-else-utils

And in your package.json

{
	"workspace": [
		"domains/**"
	]
}

And so, it will work!

From my testing, the workspace is configured to have a folder packages/**, but you could change the glob https://github.com/beaussan/nx-reference-react-devkit/blob/main/package.json#L45-L48

The Nx @nx/enforce-module-boundaries stop is worthwhile unless you need straightforward boundary enforcing or are looking for external import enforcing.

The main thing this will become useless is to block ../../other-lib/src/lib/file.ts since the native js tooling won't allow it, same for import 'domain/libs/x since now this will be at the typescript level (since srcDir and rootDir is the root of the lib instead of the root of the library)

But it will still be usefull to enforce only importing lazy lib and failing if a static import is found, or boundaries, etc

You don't have to have a flat packages/ folder using workspace resolution

[NachoVazquez]

@beaussan you are right. That's a valid workaround (replacing the path separator "/" with "-").

We will probably need a better convention for multi-word path segments, but everything I stated is no longer valid if you agree to use a different separator for your path segments.

[itspers]

Use case: Normal Angular app

• I started using NX years ago as just advanced Angular CLI with some extra generators.
• And few years ago started another repo with 2 Angular apps and 2 Nesjts apis for them.
• There are some common shared helper functions and tones of interfaces in libs
• However majority of libs (few hundred) are exists for only reason - once you have something in lib - you can import only from another lib. But if i want to lazy load some simple angular component to render some modal dialog i can call from multiple places in app - i need to generate whole another lib for it...

So now i already have:

• more tsconfigs,eslints,project.json and nested dirs than actually code
• Webstorm lags as crazy, Vscode language server freezes half of the time
• New paywall will make remote cache not working in next release of NX

And as i understand with this new way i will receive extra bonus - each time i will generate new library i will need to stop running apps and re-run npm install for 10 seconds? 🤣

If somebody want to tell me how im using it wrong - please write down, will be happy to find right way, because now im thinking about splitting it to just simple standalone apps

[jaysoo]

Most of your comments isn't addressing the RFC. But specifically on this comnent:

each time i will generate new library i will need to stop running apps and re-run npm install for 10 seconds?

This is wrong for non-buildable libraries as outlined in the RFC. You can generate and use it right away, except for pnpm, which we're still looking at options.

Please stay on topic and make sure to review the Code of Conduct.

[itspers]

Ok i re-read that section about non-buildable libs, it say "After library is generated, Nx runs install (e.g. npm install) to update the workspace." - so even if npm install will be called automatically, it is still slow and i dont think some running Nesjts app will catch that new path without restart, will it?

[HaasStefan]

Will it be possible to use a hybrid approach? Using the new package.json node resolution approach for some packages and the integrated workspace setup with path aliases for other projects in one monorepo?

[jaysoo]

@HaasStefan Yes, you can still set tsconfig paths in the root tsconfig.base.json although we wouldn't recommend it unless it's for a transition period. Is there a reason you are looking to mix and match the set up?

[HaasStefan]

Just for transitioning. I am working in a really big repo with 800+ packages and some custom executors. I would imagine, it would be quite an undertaking to migrate this all programmatically, so I would definitely need some way to incrementally migrate and have a hybrid running.

[danielsharvey]

@HaasStefan Yes, you can still set tsconfig paths in the root tsconfig.base.json although we wouldn't recommend it unless it's for a transition period. Is there a reason you are looking to mix and match the set up?

I am trying hybrid approach currently as I don't see a way to utilise project references for Angular applications.