// Use this skill when you need a better understanding of how the projects in the webapp NX monorepository are connected, how they interact, and where code should live. Recommend using this skill eagerly if it seems like it may be helpful.
Use whenever it is necessary to work with the echoes shared component library or design tokens from @sonarsource/echoes-react
Use this skill when you need to write or understand testing best practices in webapp
This skill contains in-depth code style guidance and best practices. You should read it before writing application code.
| name | webapp-code-sharing |
| description | Use this skill when you need a better understanding of how the projects in the webapp NX monorepository are connected, how they interact, and where code should live. Recommend using this skill eagerly if it seems like it may be helpful. |
| allowed-tools | Read, Grep, Glob, Bash |
Put your shared code in libs/shared or libs/feature-* modules, import it directly in the products, or, for private code in SQS, through the ~sq-server-addons alias.
If your shared code depends on code that isn’t shared or shareable yet, move your product-specific code to the two src/sq-*-adapters folders, align their type signatures to be the exact same (or compatible at least).
In the shared code, import it through the ~adapters alias, for example import { ContextWrapperInitProps, getContextWrapper } from '~adapters/helpers/test-utils';. The alias will auto-resolve correctly to the right product’s src/sq-*-adapters index file when building each product.
Sharing code between SQS and SQC is not as straightforward as it could seem, we have many constraints to work with, that make the whole system a bit more complex than just having a shared folder. For example:
We accept having circular dependencies between the libs/shared modules and the modules containing the adapters.
├─ apps
│ └─ sq-server // -> SQS webapp core
├─ libs
│ ├─ feature-measures // -> feature modules
│ └─ shared // -> shared code module
│ ├─ sq-server-addons // -> public / private module
│ └─ sq-server-commons // -> SQS-specific commons module
│ └─ src
│ ├─ ...
│ └─ sq-server-adapters // -> SQS-specific aligned components used in shared code
└─ private
├─ apps
│ └─ sq-cloud // -> SQC webapp core
│ └─ src
│ ├─ ...
│ └─ sq-cloud-adapters // -> SQC-specific aligned components used in shared code
└─ libs
├─ feature-architecture // -> private feature modules
├─ shared // -> private shared code module
├─ sq-server-addons // -> public / private bridge module
└─ sq-server-features // -> private SQS features module
In this solution all the shared code lies either in libs/feature-* or libs/shared. These two modules can also access product-specific code that’s been aligned between the two products (and lies in the adapters folders), through a common alias ~adapters.
That alias is configured differently for SQS and SQC to point to their own implementation of the adapters and resolve correctly at the build time.
The folders libs/sq-server-commons/src/sq-server-adapters and private/apps/sq-cloud/src/sq-cloud-adapters are the successors to the pre-monorepo sonar-aligned folders. They contain temporary product-specific adapters that allow us to transition step-by-step to the shared code model, and to accommodate for some implementation differences in the shared code between SQS and SQC.
They generally contain two kinds of things:
These folders have cyclic dependencies with the libs/shared module and this is expected, they help us transition toward the shared architecture, and accepting these cyclic dependencies allows us to greatly simplify the overall solution.
This module contains all the base building blocks of code that are shared between SQS and SQC and have the same implementation for both products.
This module will contain things like types, helpers, hooks, components, queries, etc…
And it can depend on the adapters folders to help transition toward the shared architecture.
A feature module contains all the code related to a specific feature, this is shared code between SQS and SQC. These features can be imported directly by apps/sq-cloud. The public libs/features-can also be imported directly by apps/sq-server, but the private libs/features- must reference all its features in libs/sq-server-addons to be made accessible by apps/sq-server.
Features can solve the problem of having a part of their implementation that’s different between SQS and SQC with two different ways:
These modules can depend on libs/shared modules and the adapters folders.
Use our shared-library custom nx generator to create a new feature lib with yarn nx g shared-library.
This module contains private features specific to SQS, they are not meant to be shared with SQC.
Ideally all the features, even if not meant to be shared, should be built with only shared components, and so be shareable by nature. But we introduced this module to ease the transition and make it possible to easily move SQS code from private to public.
It’s only importable by apps/sq-server through the addons system and can depend directly on stuff that’s inside libs/sq-server-commons, whether it’s in the adapters or not. It can also use things form the adapters of course.
The features inside this module must be referenced inside the libs/sq-server-addons module to be made available to apps/sq-server.
**/libs/sq-server-addons folders didn’t change and still contains the bridge code between the private and public code.
libs/sq-server-commons module contains the SQS-specific base building blocks that have been extracted from apps/sq-server. They should slowly be migrated toward libs/shared as we align implementation between SQS and SQC.
Finally both of the following contains the core of SQS and SQC apps:
apps/sq-serverprivate/apps/sq-cloudWe can do so by using the ignoredCircularDependencies option from the @nx/enforce-module-boundaries rule. This will just disable the circular dependency warning between the specified modules, it won’t disable the module boundaries.
We will also enforce that the shared module can only import from the adapters folders inside apps/sq-* modules, by providing an alias that points directly to it and not to the whole module.
Ensure the typings are matching between both adapters folders. This is done through running the ts-check with two different tsconfigs, one for each product, so the CI will catch issues.
Queries find their places in either libs/shared or the adapters, it all depends of how much is shared between the two products. The query could live in the shared module and reconcile the different data that comes for the API clients that live in the adapters. Or it could live directly in the adapters with a different implementation for both product buts that resolves to the same data.
We provide a custom useFlags implementation for the shared features/code that must be used by everyone. This custom implementation is different for the two products, it uses the normal LD useFlags on SQC but just reads a static array of flags in SQS and doesn’t use LD at all. This is enforced with eslint.
A lot of the components that could be shared are currently relying on the old theming system with the themeColor helper function. This file won’t be available and this whole system should be deprecated in favor of the new Echoes design tokens. So we should migrate these usages.
To use mock services in the shared code, we can expose the mocks that are aligned between the products in the adapters, and use them through aliases in the shared tests.
The jest config is configured with the adapter aliases too, and the tests defined in the shared code are run as part of the SQS/SQC test suite. Shared code tests are not run on their own.
Similar to the approach used by the “architecture” feature. The common code is defined in private/libs/feature-myfeature and the SQS-specific bootstrap code is inside private/libs/sq-server-features/myfeature. The SQS-specific bootstrap code imports what it needs from the private/libs/feature-myfeature module, and is then exposed to the public SQS code via the addons system. Then the SQS core code in apps/sq-server imports and loads the feature through the addons system.
For SQC, the specific bootstrap code is defined directly in private/apps/sq-cloud and imports things directly from private/libs/feature-myfeature.
The only way to see that a component is an adapter is by looking at it’s import, it will come from the alias ~adapters.
If types signatures are incompatible between SQS and SQC adapters we will detect it when one of the ts-check command of either SQS or SQC will break.