Adding Custom Cartridges

Implementing a site requires at least one custom cartridge. However, if you intend to create multiple sites, we suggest you create multiple custom cartridges. Each cartridge can separate functionality specific to a brand or locale, so that you can reuse most of your cartridge stack for a new site.

Adding Custom Cartridges When sgmf-scripts Is Globally Installed

If you globally installed sgmf-scripts through npm, follow these steps to add a custom cartridge:

  1. Create a folder for your project. For example:

    mkdir mysite
  2. Navigate into the folder.
    cd mysite
  3. Install the sgmf-scripts node.
    npm install sgmf-scripts
  4. Use the sgmf-scripts --createCartridge command.
    sgmf-scripts --createCartridge app_custom_storefront
    These directories and files are created in your folder:
    ├── cartridges
        └── app_custom_mybrand
            └── cartridge
                   ...
    ├── dw.json
    ├── node_modules
    └── package.json
  5. Install the dependencies required by the new cartridge:
    npm install
Note: To see all the available SFRA-commands, enter sgmf-scripts --help.

Adding Custom Cartridges When sgmf-scripts Isn't Globally Installed

If you want to avoid globally installing sgmf-scripts, follow these steps to add a custom cartridge:

  1. Create a folder for your project. For example: mysite.

    mkdir mysite
  2. Navigate into the folder.
    cd mysite
  3. Install the sgmf-scripts node via npm.
    npm install sgmf-scripts
  4. Use Node.js to call the sgmf-scripts createCartridges command.
    node node_modules/sgmf-scripts --createCartridge app_custom_mybrand
    The following directories and files are created in your folder:
    ├── cartridges
        └── app_custom_mybrand
            └── cartridge
                   ...
    ├── dw.json
    ├── node_modules
    └── package.json
  5. Install the dependencies required by the new cartridge:
    npm install
Note: To see all the available SFRA-commands, enter sgmf-scripts --help.

Updating Your package.json

Because you're not modifying the app_storefront_base cartridge directly, Salesforce B2C Commerce provides a mechanism to selectively override CSS styles and client-side JavaScript. In the package.json file, the paths property lists every cartridge with CSS and client-side JavaScript functionality customized in your site. When building your cartridge stack, the paths property lets you import functionality from CSS and JavaScript files in other cartridges and selectively override it. When you use the command-line compile tool, it compiles the JavaScript and CSS across cartridges.
  1. Navigate to the top level of your custom cartridge. For example, mysite.
  2. Open the package.json file and modify the paths property. The paths.base property points to the local directory containing app_storefront_base. Add properties for the cartridges you want to import functionality from.

    Example: adding plugin_ratings, plugin_reviews, and app_storefront_base to a custom cartridge:

      "paths": {
        "base": "../storefront-reference-architecture/cartridges/app_storefront_base/",
        "ratings": "../plugin_ratings/cartridges/plugin_ratings/",
        "reviews": "../plugin_reviews/cartridges/plugin_reviews/",
        "applepay": "../plugin-applepay/cartridges/plugin_applepay/"
      }
    }
  3. Import the CSS files you want to include and override into the my_repository/cartridges/my_cartridge/cartridge/client/default/myfile.scss file.

    The following sample global .scss file inherits most of its styles from the base cartridge. The location of the base cartridge is defined in package.json. This example uses the base property defined in the package.json to import style sheets.

    @charset "UTF-8";
    
    @import "base/variables";
    @import "bootstrap/scss/bootstrap";
    @import "base/bootstrap_overrides";
    @import "base/utilities/responsiveUtils";
    @import "font-awesome/scss/font-awesome";
    @import "flag-icon";
    @import "components/menu";
    @import "base/components/common";
    @import "base/components/footer";
    @import "components/footer";
    @import "base/components/hero";
    @import "base/components/notification";
    @import url(https://fonts.googleapis.com/css?family=Source+Sans+Pro&subset=latin-ext);
    
    body {
        font-family: 'Source Sans Pro', sans-serif;
    }
    
    .modal-background {
        display: none !important;
    }
  4. Use the path object to include JavaScript modules from other cartridges when you want to inherit and override client-side JavaScript functionality.

    The following example uses the path described by the base property to require in a client-side script in the base cartridge.

    'use strict';
    var base = require('../base/product/base');

After Creating Your Custom Cartridge

After you create your custom cartridge, do the following:

Best Practices When Creating Custom Cartridges

  • Create unit tests for models.
  • Check for possible naming collisions between cartridges.

Anti-patterns:

  • Don't override pdict variables.
  • Don't delete properties off the pdict.
  • Don't replace something in pdict with something else with a different signature.

Next Step: Building Your Cartridge Stack