Schematics - update mechanism to support "wrapper" modules

[znikola]

Introduction

With "wrapper" modules soon becoming a standard in Spartacus extensibility mechanism, we have to update installation schematics in order to support it.

Why do we have to do it

Before we answer that, we have to first explain the following: before "wrapper" modules, we didn't have a case of cross-feature dependencies, where FeatureA was extending FeatureB (e.g. Digital Payments now extends the Checkout). Therefore, the schematics were able to install features in a non-deterministic manner, where the order of installation didn't matter.
Now, we face a challenge where we have to take care of the order in which features are installed, as well as imported to spartacus-features.module.ts.

Changes and algorithm

The accommodate the "wrapper" modules, the following needs to be changed:

• Improve how the graph is created, and take into an account the sub-features cross dependencies - e.g. B2B checkout depends on the Checkout, and therefore it must be ordered after it.

• When running ng add @spartacus/schematics, we need to do a deep dependency analysis as the very first step (it will be explained later why it should be the first step) in the whole process, in order to figure out which libraries need to installed as dependency of the library which is currently being installed. This includes figuring out transitive dependencies as well.

• As a reminder, we have two types of dependencies:

  • peer dependencies, which are required have to be installed using our package manager. One example is if we import e.g. a cart model interface from the cart library. This requires the cart library to be installed, but it doesn't require the cart feature to be configured (i.e. doesn't require "cart-base-feature.module.ts" to exist).
  • on the other hand, some features require other features to already be set up in order to work properly. E.g. Checkout must ensure the Cart and Order are installed and configured.

• The problematic part of the dependency analysis is the fact we have to run the installation task to install a library, before we can actually trigger its schematics (which are responsible for configuring the feature).

  • The installation task is async, and can't be ran in the middle of the current process). --> TO BE DOUBLE CHECKED, but it seems to be the case. Update - we pulled the feature configs to projects/schematics.
  • One solution could be to pull all the feature configs from the feature libraries to the @spartacus/schematics, which then eliminates the need to install the feature library before running its schematics. This means we will first generate the feature library, and then run the installation task to actually install the package to node_modules.

• As part of the analysis step, we should also verify if the required features are already installed and / or configured. Let's call this check isFeatureSafeToConfigure()), and the verification is as follows:

  • If the feature is already configured, we can safely proceed with the process. But how to determine if the feature is configured? We will use the same check as described below (look for recognizeFeature().
  • If the feature is not configured, we can not proceed, and will abort the process with an appropriate message which explains why we can not proceed. The reason why we don't want to install and configure the potentially missing features is a case when customers might've dismantled the required feature's module - in this case we would install the "missing" feature again, which is a wrong behavior.
  • The only exceptions to the above case are the following cases:
    • when Spartacus is being added for the very first time. Perhaps there is an already coded check which we can use to determine if Spartacus is already configured, and we can set this to a nested internal object in the schematics options (to be checked if this is possible). For this to work, we have to perform the analysis as the very first step in the process, before we actually scaffold the Spartacus file structure.
    • In case we're doing a "dirty" installation in the application which already has Spartacus configured, and we need to install e.g. Checkout feature: we can check if the app's package.json contains the @spartacus/checkout dependency. If it doesn't, it means the Checkout wasn't even installed before, and we can safely proceed to generate the default configuration as if it was a clean installation
  • What can be used to analyze if the feature is configured? We will use a so called "markers", which are just module import identifiers. E.g. when installing Digital Payments feature, we need to check if any Checkout feature is configured (Base, B2B or Scheduled Replenishment) by looking for the CheckoutModule import. Let's call this process recognizeFeature(). We will iterate through the list of feature modules, and look for the marker. For each feature module, we will:
    • Look for the marker in the dynamic imports
    • Fall back to looking in the NgModule's import[] array

• once the deep analysis is done, the list of features to be installed will also include the set of features which were selected by the customer in the prompt, and we can start installing and configuring features.

• once the process of installing features begins, we must not repeat the deep dependency analysis, as everything was already analyzed. For this to work, we have to propagate some kind of a flag, as we're invoking another schematic which doesn't have a notion of the previous analysis. The flag's name should indicate the flag is intended for a private usage, and that it shouldn't be passed by external users.

• Wrapper module schematic

  • it will generate the "wrapper" modules for the given "marker" name. E.g. ng g @spartacus/schematics:wrapper --name=CheckoutModule
  • The schematic is private
  • We need to expand the FeatureConfig's options by adding a new config option called wrappers (the name is TBD):

    /**
     * Configuration for generating the wrapper modules.
     *
     * The key is the feature name for which wrapper module is being generated.
     * The value is the feature module configuration which will be
     * used to determine if the wrapper module is already created.
     *
     * E.g., the B2B Checkout's configuration is:
     *
     *
     * wrappers: {
     *  [CLI_CHECKOUT_BASE_FEATURE]: {
     *  importPath: '@spartacus/checkout/base',
     *  name: 'CheckoutModule',
     * }
     *
     * // TODO:#schematics - adjust the import paths
     * While the CDC's configuration is a bit more complex:
     * wrappers: {
     *  [CLI_USER_ACCOUNT_FEATURE]: {
     *  importPath: '@spartacus/cdc/account',
     *  name: 'CdcAccountModule',
     *  },
     *  [CLI_USER_PROFILE_FEATURE]: {
     *    importPath: '@spartacus/cdc/profile',
     *    name: 'CdcProfileModule',
     *   },
     *  },
     */
    wrappers?: Record<string, Module>;

  • The schematic will be invoked on the fly, during the installation of features. E.g. when installing Scheduled Replenishment Checkout, the installer will:
    • figure out the Repl's feature dependencies and order them
    • start installing the features
    • when it reaches the installation of B2B Checkout, it will invoke the wrapper schematic for it. But how would the installer know it needs to invoke the schematic? It will know by looking at the .wrappers schematic config of the B2B Checkout feature. It will use it to generate the arguments for the wrapper schematics: --feature=CheckoutModule --import=@spartacus/checkout/base
    • [schematic] will look use the given "marker" name and iterate through the installed feature modules. Once it finds a module which contains the identifier of CheckoutModule, it will start examining it.
    • [schematic] will first check if the CheckoutModule is statically imported from the given import path. If so, the wrapper module is already created, and we've just found it.
    • [schematic] if the static import was not found, we need to confirm if CheckoutModule is being dynamically imported. If so, we found a vanilla feature configuration module, and we need to:
      • create the wrapper module
      • switch the dynamic import from vanilla's feature configuration module to point to the newly created wrapper module
    • [installer] Once the wrapper module has been created, the installation of B2B Checkout assumes the existence of wrapper module, and continues to eagerly (set the lazy flag to false) install the CheckoutB2BModule by statically importing it to the wrapper module, which looks like this now:

    import { NgModule } from '@angular/core';
    import { CheckoutB2BModule } from '@spartacus/checkout/b2b';
    import { CheckoutModule } from '@spartacus/checkout/base';
    @NgModule({
      imports: [CheckoutModule, CheckoutB2BModule],
    })
    export class CheckoutWrapperModule {}

    • [installer] when it reaches the installation of Repl Checkout, it will invoke the wrapper schematic for it, and repeat the process. The generated schematic arguments will be --feature=CheckoutB2BModule --import=@spartacus/checkout/b2b (note the B2B module this time).
    • [installer] the order of the feature modules imports will be sorted according to the cross-feature graph. In case the NgModule's imports[] contains any import which is not from @spartacus, we won't perform the ordering. Instead we will import the feature module at the end of the imports array, and will generate a comment in the code above it saying "please make sure this import is ordered correctly".
    • [installer] if Digital Payments is also to be installed, the process is repeated. At the end, the checkout wrapper module will look like this:

    import { NgModule } from '@angular/core';
    import { CheckoutB2BModule } from '@spartacus/checkout/b2b';
    import { CheckoutModule } from '@spartacus/checkout/base';
    import { CheckoutScheduledReplenishmentModule } from '@spartacus/checkout/scheduled-replenishment';
    import { DigitalPaymentsModule } from '@spartacus/digital-payments';
    @NgModule({
      imports: [
        CheckoutModule,
        CheckoutB2BModule,
        CheckoutScheduledReplenishmentModule,
        DigitalPaymentsModule,
      ],
    })
    export class CheckoutWrapperModule {}

    while the checkout feature module looks like:

    import { NgModule } from '@angular/core';
    import {
      checkoutB2BTranslationChunksConfig,
      checkoutB2BTranslations,
    } from '@spartacus/checkout/b2b/assets';
    import { CheckoutB2BRootModule } from '@spartacus/checkout/b2b/root';
    import {
      checkoutTranslationChunksConfig,
      checkoutTranslations,
    } from '@spartacus/checkout/base/assets';
    import {
      CheckoutRootModule,
      CHECKOUT_FEATURE,
    } from '@spartacus/checkout/base/root';
    import {
      checkoutScheduledReplenishmentTranslationChunksConfig,
      checkoutScheduledReplenishmentTranslations,
    } from '@spartacus/checkout/scheduled-replenishment/assets';
    import { CheckoutScheduledReplenishmentRootModule } from '@spartacus/checkout/scheduled-replenishment/root';
    import { provideConfig } from '@spartacus/core';
    @NgModule({
      imports: [
        CheckoutRootModule,
        CheckoutB2BRootModule,
        CheckoutScheduledReplenishmentRootModule,
      ],
      providers: [
        provideConfig({
          featureModules: {
            [CHECKOUT_FEATURE]: {
              module: () =>
                import('./checkout-wrapper.module').then(
                  (m) => m.CheckoutWrapperModule
                ),
            },
          },
        }),
        provideConfig({
          i18n: {
            resources: checkoutTranslations,
            chunks: checkoutTranslationChunksConfig,
          },
        }),
        provideConfig({
          i18n: {
            resources: checkoutB2BTranslations,
            chunks: checkoutB2BTranslationChunksConfig,
          },
        }),
        provideConfig({
          i18n: {
            resources: checkoutScheduledReplenishmentTranslations,
            chunks: checkoutScheduledReplenishmentTranslationChunksConfig,
          },
        }),
      ],
    })
    export class CheckoutFeatureModule {}

    and digital payments feature module looks like (no dynamic import, and no root module import).

    import { NgModule } from '@angular/core';
    import { I18nConfig, provideConfig } from '@spartacus/core';
    import {
      dpTranslationChunksConfig,
      dpTranslations,
    } from '@spartacus/digital-payments/assets';
    @NgModule({
      imports: [],
      providers: [
        provideConfig(<I18nConfig>{
          i18n: {
            resources: dpTranslations,
            chunks: dpTranslationChunksConfig,
            fallbackLang: 'en',
          },
        }),
      ],
    })
    export class DigitalPaymentsFeatureModule {}

Additional tasks

Additional tasks that we can do are:

• Introduce a new prompt which will users if they're using B2C or B2b features.
  • The result of this prompt will be used later to install the B2B variant of some of the features (e.g. we can immediately install B2B checkout)