Extend a Sass File

This topic applies to

Applies to

SuiteCommerce Advanced



Making changes to core JavaScript source files or changing any vital functionality of the application can make migrating to future releases difficult. Before making changes to SuiteCommerce Advanced (SCA), see Best Practices for Customizing SuiteCommerce Advanced.

SCA enables you to customize your web store to easily apply global style changes while supporting migration to later versions. When customizing styles, you create a custom module that overrides specific Sass variables already defined in the BaseSassStyles module. You then redefine application dependencies so that base Sass styles import your customizations in the correct order.

This example shows how to create a custom module to change the default background and foreground colors.

To extend a Sass file:

  1. Create the directory structure to store your custom module.

    1. Create a directory called extensions. Where you place this depends on your implementation.

      • If implementing 2019.2 and later, create the extensions directory within the SC_xxx directory within your root source directory. Examples: SC_20.1/extensions, SC_19.2_Live/extensions.

      • If implementing 2019.1 and earlier, create the extensions directory within the Modules directory. For example: Modules/extensions.

    2. In the extensions directory, create a subdirectory called CustomSass@1.0.0.

      When creating a new custom module, the module name must be unique. You must not have duplicate module names, even if those modules reside in different folders.

    3. In the CustomSass@1.0.0 directory, create a subdirectory called Sass.

    In general, when creating custom modules, you should create a directory structure similar to that described in the procedure above. See Organize Source Code for Custom Modules for more information.

  2. Create a Sass file.

    1. In the Sass directory, create a new file called _custom-sass.scss.

    2. Add Sass variable definitions to this file.

      These variable definitions override the base Sass variables defined in the BaseSassStyles module. See Design Hierarchy for more information.

      $sc-color-primary: #0000ff; // originally #f15c28; $sc-color-secondary: #00ff00; //originally #5B7F8C; $sc-color-theme: #00ff00; //originally #5B7F8C; $sc-color-link: #00ff00; //originally #2f9ac3; $sc-color-theme-light: #00aa00; // originally #9cb6bf $sc-color-theme-background: #000000; $sc-color-dark-copy: #e7d13b; // originally #1f2223; $sc-color-copy: #ede39f; //originally #404040; body { background-color: $sc-color-theme-background; }
  3. Create the ns.package.json file.

    1. Create a file called ns.package.json in the CustomSass@1.0.0 directory.

    2. Add the following to the ns.package.json file.

      { "gulp": { "sass": [ "Sass/**/*.scss" ] } }
  4. Update the distro.json file.

    1. Add an entry for your CustomSass@1.0.0 module to the distro.json file.

      • If implementing 2019.2 and later, the distro.json file is located in the Advanced directory of the SCA source code. Examples: SC_20.1/Advanced/distro.json, SC_19.2_Live/Advanced/distro.json

        { "name": "SuiteCommerce Advanced Live", "version": "2.0", "isSCA": true, "buildToolsVersion": "Live", "folders": { "thirdPartyModules": "../../third_parties", "distribution": "../LocalDistribution", "deploy": "../DeployDistribution" }, "modules": { "extensions/CustomSass": "1.0.0", "Account", "Balance", ...
      • If implementing 2019.1 and earlier, the distro.json flie is located in the root directory of your SCA source code.

      { "name": "SuiteCommerce Advanced Mont Blanc", "version": "2.0", "buildToolsVersion": "1.1.0", "folders": { "modules": "Modules", "suitecommerceModules": "Modules/suitecommerce", "thirdPartyModules": "Modules/third_parties", "distribution": "LocalDistribution", "deploy": "DeployDistribution" }, "modules": { "extensions/CustomSass": "1.0.0", "suitecommerce/Account": "2.1.0", ...
    2. Split the BaseSassStyle entry in the sass object and add your custom module between them. This ensures that the Sass variables are loaded in the correct order as follows:

      1. The main-variables Sass file.

      2. The custom Sass variables defined in the CustomSass module.

      3. Additional Sass files of the BaseSassStyles module. Including these last ensures that the additional Sass files import the custom variable definitions.

      { "module": "BaseSassStyles", "include": [ "main-variables" ] }, "CustomSass", { "module": "BaseSassStyles", "include": [ "main-atoms", "main-molecules", "bootstrap-overrides" ] },


      You must define these dependencies for each application whose Sass variable you want to change.

  5. View your changes.

    If you are running a local server, you can view your changes by reloading your website. See SCA on a Local Server for more information.

    If you are viewing your site in NetSuite, you can deploy your changes using the developer tools. See Deploy to NetSuite for more information.