⚡ The Super Power of Conventions with Nx
Supporting Hundreds of Project Configurations in Your Large Repository
In this article, I’ll dive into why following conventions is essential, especially in large repositories with many projects.
We’ll also explore an alternative approach using an Nx plugin to centralize configurations instead of relying solely on generators.
What does it mean to structure a code repository by convention?
Structuring a code repository by convention means organizing the files, the folders, and the configurations in a specific way that follows established best practices and agreed-upon standards within a team or community.
This helps to ensure consistency, clarity, and ease of use for all contributors.
Which conventions do I need to adhere to?
None of them and all of them!
Unfortunately (or fortunately), there is no perfect answer to that question. Each organization has its way of working and structuring its codebase.
Enforcing a convention on an existing codebase can be difficult and usually introduces extra complexity instead of reaping its benefits.
The idea is to adopt what can be beneficial in your way of working from various conventions used in the community.
By implementing some rules and mechanisms, you will ensure that you can align your code and way of working in the long term.
How Nx is helping with that?
Probably some of you remember the time before Nx when all repositories were looking like Frankenstein architecture.
Just by integrating Nx, you’ll implicitly follow a list of conventions related to the code code organization and naming convention.
Nx also provides some recommendations concerning the way you could organize your libraries by typing them.
You can find more advanced approaches like the Domain-Driven Design from Manfred Steyer.
The Nx plugin is perfect for defining conventions right?
Similar to the nx-ddd-plugin by Manfred, you can create your own plugin to generate code and rules that follow conventions.
However, over time, you may find that maintaining many complex generators becomes challenging and time-consuming.
That’s why I always recommend centralizing configurations instead of creating complex generators that contain all your customizations.
Which configurations are we talking about?
As you know, each Nx project contains numerous configurations: eslint, jest, vite, webpack, typescript, cypress, and more.
These configurations are often duplicated and can be centralized in an Nx Plugin using the internal extends system or by using an import(‘…’).
Instead of using a flat structure of generators, executors, and migrations, we can organize configurations and utilities by context.
I usually organize my configurations by:
- Technology: linting rules, jest configs, tsconfig, etc., depending on the framework and technology used.
- Project Type: generators for feature and domain libraries are different.
- Domain: if you have a high level of domain, such as a domain per team, you can specify different ways of working and group configurations accordingly.
For example, for eslint configurations, the structure could look like this:
Share your convention
We typically use Nx in a mono repo approach to share configurations, and I always recommend this when there are many dependencies between applications/teams.
However, if your applications are independent, or if you need to maintain isolation between repositories for valid reasons, you can still benefit from aligning code and re-using configurations by sharing them in a published Nx plugin.
You can also distribute multiple plugins across your organization, but it means installing multiple packages.
Conclusion
As you can see, conventions are highly recommended when dealing with many projects in a large organization.
It’s important to implement conventions incrementally as you gain experience with your structure. A good convention set usually consists of a mix of internal organization rules and popular external approaches.
The Nx plugin greatly assists in this, but its power is enhanced even more when configurations are centralized instead of generated.
🚀 Stay Tuned!
