Add 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.

All available LINK and plug-in cartridges are on GitHub. Plug-in cartridges are in the SFRA project in GitHub. You can Include link and plug-in cartridges on your cartridge path and base path as you would any other cartridge in your stack.

Note: Don't rename the app_storefront_base cartridge or other provided plug-ins. Keep your version of the app_storefront_base cartridge and other plug-ins up-to-date. By doing so, you ensure that you have the latest bug fixes and performance improvements.

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:

Create a folder for your project. For example:
```
mkdir mysite
```
Navigate into the folder.
```
cd mysite
```
Install the sgmf-scripts node.
```
npm install sgmf-scripts
```

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

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:

Create a folder for your project. For example: mysite.
```
mkdir mysite
```
Navigate into the folder.
```
cd mysite
```
Install the sgmf-scripts node via npm.
```
npm install sgmf-scripts
```

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

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.

Navigate to the top level of your custom cartridge. For example, mysite.
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/"
  }
}
```

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;
}

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:

Upload Your Code to the platform. If you are using the command line to watch and upload code, you can update your dw.json file.
Add the Cartridge to the Cartridge Path
Disable Page Caching.
Generate Search Indexes.
View the Storefront.

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.