The distro.json and ns.package.json Files

To determine which files to include with the Distribution folder of SCA, Gulp.js uses two configuration files:

distro.json
ns.package.json

The distro.json file resides in the following location, depending on your implementation:

If implementing the 2020.1 release and later, this file is located within the SC_xxx/Advanced directory within your root source directory. For example: SC_20.1/Advanced
If implementing 2019.2, this file is located within the *_Live/Advanced/ directory within your root source directory. For example: SC_19.2_Live/Advanced/
If implementing 2019.1 and earlier, this file is located within the top level of the SCA directory.

The distro.json file defines the modules that are included in SCA. It also specifies additional configuration information.

Gulp.js parses this file to determine which files within the Modules directory to combine or copy into the Distribution folder. The distro.json file contains the following parameters:

name: specifies the name of the application. By default this value is SuiteCommerce Advanced <version>.
version: specifies the application version.
modules: lists the modules SCA uses. Each module is listed on a separate line and uses the following format:

"<module_name>": "<module_version>"

By default the SCA modules are listed in alphabetical order because there are no dependencies between modules. However, when customizing SCA, your modules may have dependencies on other modules. When dependencies exist, you must ensure that any required modules are listed before other modules.
taskConfig: defines the gulp tasks required by the build process. In general, you do not need to edit these tasks.
copy: specifies the source and target paths when copying files to the Distribution directory.

Although the distro.json file defines the modules that are included in SCA, the ns.package.json file determines which files within an individual module are included. Each module included in the distro.json file must have a corresponding ns.package.json file. The ns.package.json file:

Must be at the top level of the module folder
Uses the structure shown in the following examples

JavaScript Example

            {
   "gulp": {
      "javascript": [
         "JavaScript/*.js"
      ]
   ,   "templates": [
         "Templates/*.txt"
      ]
   ,   "ssp-libraries": [
         "SuiteScript/*.js"
      ]
   ,   "services.new": [
         "SuiteScript/*.Service.ss"
      ]
   }
}

TypeScript Example

            {
   "gulp": {
      "javascript": [
         "JavaScript/*.js"
         "JavaScript/*.ts
      ]
   ,   "templates": [
         "Templates/*.txt"
      ]
   ,   "ssp-libraries": [
         "SuiteScript/*.js"
      ]
   ,   "services.new": [
         "SuiteScript/*.Service.ss"
      ]
   }
}

In the preceding JavaScript example, there is a mapping between file types and partial paths to the location of the files. In general, Gulp.js uses wildcards to specify the contents of a directory. For example, JavaScript/*.js includes all files with the .js extension that are in the JavaScript folder. However, when creating your own modules, you can point to specific files within a directory, for example:

          ...
"javascript": [
         "JavaScript/MyJavaScriptFile.js"
      ]
...

The types shown in the preceding examples (javascript, templates, services, etc.) correspond to a specific Gulp task. Gulp tasks determine how certain file types are handled. For example, the javascript Gulp task causes all JavaScript files within a distribution to be compiled into a single file. Other Gulp tasks are responsible for copying files from the Modules directory to the Distribution directory.

If you are using the 2019.2 release of SCA or later, many of the source files are written in TypeScript with .ts filename extensions. In this case, the ns.package.json file uses JavaScript/*.ts to include .ts files as JavaScript. For example:

          ...
"javascript": [
         "JavaScript/*.js",
         "JavaScript/*.ts"
      ]
...

As a best practice, use only the default Gulp tasks when creating or editing a module. To use a custom file type within the ns.package.json file, you must create your own custom Gulp task.

Gulp tasks are stored in the following location:

SCA/gulp/tasks

Note:

This directory is created when you install Gulp.js. It is not included in the downloaded version of the SCA source directory. See Set Up the Commerce Developer Environment for more information.

JavaScript Example

TypeScript Example

Related Topics