Nx workspace structure for NestJS and Angular

nx-structure-angular-nestjs.md

Nx

https://nx.dev/

Nx is a suite of powerful, extensible dev tools to help you architect, test, and build at any scale — integrating seamlessly with modern technologies and libraries while providing a robust CLI, caching, dependency management, and more.

It has first-class support for many frontend and backend technologies, so its documentation comes in multiple flavours.

Principles

Below is the sample folder structure for Nx with NestJS and Angular. Our principles are:

• SCAMs (single component Angular modules) for tree-shakable components, meaning each component will have a respective module. For example, a RegisterComponent will have a corresponding RegisterModule, we won't declare RegisterComponent as part of AuthModule for example.
• Mostly everything will stay in the libs folder. New modules, new models, new configurations, new components etc... are in libs. libs should be separated into different directories based on existing apps. We won't put them inside the apps folder. For example in an Angular, it contains the main.ts, app.component.ts and app.module.ts

Structure

.
└── root
    ├── apps
    │   ├── api                       <-- nestjs
    │   └── client                    <-- angular
    └── libs (1)
        ├── api                       <-- grouping folder (dir)
        │   ├── core                  <-- grouping folder (dir)
        │   │   └── feature           <-- nest:lib (2)
        │   ├── feature-1             <-- grouping folder (dir)
        │   │   ├── data-access       <-- nest:lib, service + entities
        │   │   ├── feature           <-- nest:lib, module + controller
        │   │   └── utils             <-- nest:lib, things like interceptors, guards, pipes etc...
        │   └── feature-2             <-- grouping folder (dir)
        │       ├── data-access       <-- nest:lib, service + entities
        │       ├── feature           <-- nest:lib, module + controller
        │       └── utils             <-- nest:lib, things like interceptors, guards, pipes etc...
        ├── client                    <-- grouping folder (dir)
        │   ├── shell                 <-- grouping folder (dir) 
        │   │   └── feature           <-- angular:lib (3)
        │   ├── feature-1             <-- grouping folder (dir)
        │   │   ├── data-access       <-- angular:lib, service, API calls, state management)
        │   │   ├── feature           <-- grouping folder (dir) or lib (4)
        │   │   │   ├── list          <-- angular:lib e.g. ProductList
        │   │   │   └── detail        <-- angular:lib e.g. ProductDetail
        │   │   └── ui                <-- grouping folder (dir)
        │   │       ├── comp-1        <-- angular:lib, SCAM for Component
        │   │       └── pipe-1        <-- angular:lib, SCAM for Pipe
        │   └── shared                <-- grouping folder (dir)
        │       ├── data-access       <-- angular:lib, any Service or State management to share across the Client app)
        │       ├── ui                <-- grouping folder (dir) (5)
        │       └── utils             <-- angular:lib, usually shared Guards, Interceptors, Validators...)
        └── shared                    <-- grouping folder (dir), most libs in here are buildable @nrwl/angular:lib)
            ├── data-access           <-- my shared data-access is usually models, so it is a lib
            ├── ui                    <-- optional grouping folder (dir), if I have multiple client apps
            └── utils                 <-- optional grouping folder (dir), usually validation logic or shared utilities
                ├── util1             <-- lib
                └── util2             <-- lib

1. lib vs grouping folder (dir)

• a dir is just a directory.
• a lib is generated by using Nx schematics

2. api-core-feature: this is the CoreModule that will include all initial setups like Config and Database Connection etc... and importing other Modules. CoreModule will be imported by AppModule
3. client-shell-feature: Same idea as NestJS's CoreModule. This Shell includes RouterModule.forRoot()
4. client-feature-1-feature: This can either a dir or a lib.

• If this feature only has one Routable component, it is a lib.
• If it has multiple Routable components, then it should be a dir. For example:

└── feature
    ├── list (angular:lib e.g ProductList)
    └── detail (angular:lib e.g. ProductDetail)

feature usually contains the ContainerComponent and the RouterModule.forChild()

5. client-shared-ui is a little tricky. The general recommendation is to NOT grouped stuffs by type like components, pipes etc... into a single module but because these are shared, it is easy to get quite messy if not grouped by type. This is your call. We prefer to have a Single Component Per Module (SCAM) for each angular library.

This structure is proposed by my friend Chau Tran and I am applying it for my latest project!

Why?

Following the above structure will bring three advantages:

• Consistency: eliminate mental overhead when we don't have to think about where to put what in a big repo having from two apps and above.
• Promote Single Component Per Module (SCAM) + Buildable libraries to get the benefits from the nx affected commands.
• Prevent circular dependencies issue.

Some rules of thumb

• data-access: data-access can import other data-access. But never import its feature . For example: user/data-access can import from product/data-access but it will never import from user/feature
• feature: can only import its own data-access or the global shared/data-access. For example: user/feature can import from user/data-access but never from product/data-access.
• util: Utils can be shared across data-access, util.

Example

https://github.com/trungk18/angular-spotify

@Benny739

Hi @nartc and @tonivj5,
we added a 5th type in our app called "service". This type can import everything besides type:feature. We had multiple problems without this 5th type:

• Smart guards

Not sure what you mean by "smart guards" or why they can't reside in libs/api/feature/utils or libs/api/shared/utils/.

• Global services or services that where shared between features

Why couldn't you include services shared between features in libs/api/shared/data-access?

• Smart components that are shared between features

Why not libs/client/shared/ui?

With this new type we're having no problems now in our app and everything works how it should.

We also added 2 more layers besides type: platform & scope. Basically to have more order in what can import what (backend, frontend, android etc) and also to make everything more domain specific. E.g. we had multiple services which where shared between multiple frontend apps but belonged to 1 domain. In this case:

Why not keep these services under their respective lib domain directory under data-access and just reference that from your other domains?

platform: frontend -> can be imported by any frontend project
scope: domain1 -> can only be imported by domain1
type: service -> as described above

Hi @trungk18, @nartc,
I have a couple of disagreements with your choice structure:

1. I don't think you should have top-level api and client directories.

• You should keep implementation details or file types out of your structure and constrain it to domains and features as specified in the Angular Enterprise MonoRepo Patterns book page 14.
• This will also flatten your structure greatly and make your MonoRepo more navigable, manageable and understandable, by reducing your project name lengths.
• Instead, you should be using platform: or framework: tags (usually, the more specific you can be, the better, within reason), as specified in the Angular Enterprise MonoRepo Patterns book page 14 along with lint rules to impose project constraints.

2. This is more of a nitpick, but I also realize that you chose data-access as it's specified in the book.

• However, I prefer to name such projects domain as they don't just include data-access (services, repositories...), but also models (dto's, interfaces...) as well as business logic.
• Depending on how large your domain projects are, you could also convert domain into a directory, and split the implementation down further into data-access, models, and business projects to take further advantage of NX dependency graph optimizations.

@Falven Thank you for the comment and for voicing your suggestions.

I think, as most questions in programming, that it depends on the teams and projects. I personally like grouping top directories because I prefer have clear “path” in the import: @scope/app-dir/lib instead of @scope/app-lib

Also, I rarely change the module names that get generated and I pefer to have shorter module names than longer.

Last but not least, the lib type is very dependent on projects. I like domains a lot and have used it before. Lately, I use infra as a lib type as well.

@nartc @trungk18 Thank you for sharing your work, it's awesome!
I have a couple of questions for you if you don't mind :)

I'd like to use SCAM as well but I'm reluctant to create one lib per component. I understand that you follow this principle to leverage partial builds but are there other benefits? IMHO, it seems a big cognitive overhead to have so many libs because creating a new lib generates a bunch of new configuration files and that makes browsing files harder in the long run. By the way, are dependencies graph still readable in this case?

In my company, I have two more "dimensions" : I have two business apps each with a back and a front office. How would you handle this case?
Would you keep the structure as flat as possible or would you nest folders like this:

.
└── apps
    ├── business-app1
    │   ├── front-office
    │   │   ├── client
    │   │   └── api
    │   └── back-office
    │       ├── client
    │       └── api
    └── business-app2
        ├── front-office
        │   ├── client
        │   └── api
        └── back-office
            ├── client
            └── api

And how would you organize libs to share libs between the client and the api of a same business app and between api (or client) of different business apps?

I have the feeling that it can quickly get complex whereas we are a small company and a small team dev!

Keep up the good work!

@nartc Is disabling "showCircularDependencies" still an option in the current version of Nx? Seems like the config files have changed since you recommended disabling this option for TypeORM entity libs. Is there somewhere else to put this option or an equivalent option, or is that strategy no longer viable? It seems like the other option (putting all entities in one shared lib) would be a chokepoint in the dep graph, causing everything using any entity to be considered affected when any entity changes.

For the record, here's a huge monorepo structure to check for inspiration too:
https://github.com/Energinet-DataHub/greenforce-frontend