File structure

The module has to have a proper structure so CLI can read it properly and copy parts of modules in the right places.

The important directories in the module structure include:

• The middleware directory is the place with all files required by an extension you’re delivering through your module.
• The next and nuxt directories contain components, hooks/composables, pages, and lang directories that are dedicated to the given frontend app.
• The shared directory contains all the files that are shared between Next and Nuxt applications. For example utils or assets.
• The module.json file with required properties so the module could work properly.

Module.json file

Each module should have its own module.json file that contains dependencies required by middleware and the frontend apps (accordingly for next & nuxt). The CLI during the module installation adds the necessary dependencies to the package.json files in the apps.

The CLI will be installing modules by copying the files from the respective directories in the module into the applications. The module will be downloaded from the repository to the temporary folder or while using dev flag from a local directory.

Possible properties that can be used in the module.json file:

• name (string) - full module name used as information for the user during installation through the CLI tool.
• supportedEcommerces (array) - array containing names of e-commerce that module support e.g ['sapcc', 'sapcc-b2b'].
• dependencies inside nuxt, nextjs, middleware (object) - specific dependencies to work either middleware or nextjs/nuxt app can be defined here.

Example of module.json file:

{
    "name": "SAP Checkout",
    "nuxt": {
        "dependencies": {
            "lodash": "2.4.0"
        }
    },
    "next": {
        "dependencies": {
            "lodash": "2.4.0"
        }
    },
    "supportedEcommerces": [
        "sapcc"
    ]
}

Installation script pattern

Currently, there are particular patterns baked inside CLI that are run when every module is installed.

Here's a list of all patterns that are run when the user installs a module with CLI arguments (e.g. add-module quick-order --dev="path-to-module/quick-order").

• The middleware area
  • middleware directory is copied into app/storefront-middleware/sf-modules/quick-order.
  • modules.json property middleware.dependencies object is taken and merged with app/storefront-middleware/package.json.
• The nextjs area
  • nextjs directory is copied into app/storefront-unified-nextjs/sf-modules/quick-order.
  • nextjs/lang/{locale}.json (where locale could be e.g. en or de) file is copied into app/storefront-unified-nextjs/lang/{locale}/{moduleId}.json (where moduleId is module identifier in our case quick-order) and add import into app/storefront-unified-nextjs/lang/{locale}/index.ts as barrel import and then export all language files for i18n.
  • modules.json property nextjs.dependencies object is taken and merged with app/storefront-unified-nextjs/package.json.
• The nuxt area
  • nuxt directory is copied into app/storefront-unified-nuxt/sf-modules/quick-order.
  • nuxt/lang/{locale}.json (where locale could be e.g. en or de) file is copied into app/storefront-unified-nuxt/lang/{locale}/{moduleId}.json (where moduleId is module identifier in our case quick-order) and add import into app/storefront-unified-nextjs/lang/{locale}/index.ts as barrel import and then export all language files via defineI18nLocale for i18n.
  • modules.json property nuxt.dependencies object is taken and merged with app/storefront-unified-nuxt/package.json.
• The shared area
  • shared/utils directory is copied into app/storefront-unified-{nuxt,next}/sf-modules/quick-order/utils.
  • shared/assets directory is copied into app/storefront-unified-{nuxt,next}/public/quick-order.

Custom installation script instructions

In module installation script you can add custom logic containing copying over module files, doing changes to the users’ project, or initialization configuration. To ease the writing of the installation script, we’ve created module-kit package - please consult its readme. For examples of module installation scripts, please see modules repository.