Next-generation platform

Configuring local development server


To load the application UI in a development environment, ensure that the micro-frontend and store-root-config applications are running.

To consolidate the execution of all the micro-frontend applications within the Sterling Store Engagement application, use the command-line utilities and scripts that are provided. The command-line utilities and scripts rely on the app-config.json, which describes context root, ports, and so on, for all the micro-frontend applications. It also allows certain routes to proxy to a remote server that allows developers to choose the application they want to run locally.

Developers can choose to serve the micro-frontend applications from a remote server instead of running locally. As a developer you can configure either the local developer toolkit instance or the development or QA cloud instance as a remote server. If the remote server is HTTPS enabled, a secure connection to the server is established by using the configured p12 certificate file and certificate password. By configuring the remote server, you can choose the appropriate routes or micro-frontend applications to serve from a local server and from a remote server. After you generate and download the client certificate, configure the path of client certificate in the app-config-overrides.json file. For more information about generating and downloading the client certificate, see Generating client certificates.

Note: In the local developer toolkit or cloud instance, make sure that the OpenID Connect (OIDC) or Single sign-on (SSO) is not enabled to use as a remote server.
The following sample code illustrates the app-config.json file:
{
  "name": "store-frontend",
  "devServerConfig": {
    "port": 9000,
    "contextRoot": "/isf/store-frontend"
  },
  "routes": {
    "app-shell": {
      "devServerConfig": {
        "port": 4200,
        "contextRoot": "app-shell"
      }
    },
    "login": {
      "devServerConfig": {
        "port": 4204,
        "contextRoot": "login"
      }
    },
    "nav-bar": {
      "devServerConfig": {
        "port": 4300,
        "contextRoot": "nav-bar"
      }
    },
    "home": {
      "devServerConfig": {
        "port": 4203,
        "contextRoot": "home"
      }
    },
    "customer-profile": {
      "devServerConfig": {
        "port": 4202,
        "contextRoot": "customer-profile"
      }
    }
}}
Each micro-frontend application root package.json provides the script, yarn start-app to start the feature application. As a developer, you can override app-config.json by providing app-config-overrides.json to run the micro-frontend applications in the following modes:
  • To run a few micro-frontend applications locally, complete the following steps:
    • Copy and paste the micro-frontend application or route name from the app-config.json file to the routes object in app-config-overrides.json.
    • For the application name, set useRemote=false.
    • Set serveAllAppsFromLocal=false to ensure that the remaining micro-frontend applications are served from a remote server that is configured in the remoteServerConfig object.
  • To run all the micro-frontend applications locally, set "serveAllAppsFromLocal": true in app-config-overrides.json. In this case, the useRemote flag for individual micro-frontend applications and remote server configurations is ignored.

The yarn start-app command parses app-config-overrides.json and starts the micro-frontend applications locally, which are configured as "useRemote": false. The micro-frontend applications that are not listed in app-config-overrides.json or with useRemote: true are served from a remote server that is configured in remoteServerConfig object in the app-config-overrides.json file.

Note: If you set useRemote: true, it is recommended that you launch the Google Chrome browser in the web security disabled mode. This is to ensure that your browser does not block any cross origin HTTP requests that are made to the remote application server from your local application.
  • For Windows, run the following command:
    chrome.exe --user-data-dir="C:\tmp" --disable-web-security
  • For Mac, run the following command:
    open /Applications/Google\ Chrome.app --args --disable-web-security --user-data-dir=/tmp
The following sample code illustrates app-config-overrides.json:
{
    "name": "store-frontend",
    "serveAllAppsFromLocal": false,
    "remoteServerConfig": {
        "hostName": "store-dev.oms.supply-chain.ibm.com",
        "port": 443,
        "https": true
        "options": {
           "pfx":"/path/to/certificate.p12",
           "passphrase":"<password>"
       }
    },
    "routes": {
        "app-shell": {
            "useRemote": false
          },
          "login": {
            "useRemote": false
          },
          "nav-bar": {
            "useRemote": false
          },
          "home": {
            "useRemote": false
          },
          "backroom-pick": {
            "useRemote": false
          }
    }
}

The following tables define the JSON schema of app-config.json and app-config-overrides.json:

Table 1. app-config.json schema definition
Element or Attribute Description
name Name of the store application. 
"devServerConfig":{
   "port":1111,
   "contextRoot":"/isf/store-frontend"
}
 The development server configuration at the root level indicates the port number and context root that are used by the store-root-application.
  • port: The port number of the store root application. Supports only numeric value.
  • contextRoot: Specifies the context root of the store root application. Supports only string value.
 
"remoteServerConfig": {

        "hostName": "store-dev.oms.supply-chain.ibm.com",
        "port": 443,
        "https": true,
        "options": {
           "pfx":"/path/to/certificate.p12",
           "passphrase":"<password>"
       }
}
 The remote server configuration that is used to serve angular applications from a remote server. This configuration allows developers to run specific angular applications in local, and the remaining to be served from a remote server. The remote server might be the OMS DTK instance, or development or QA cloud instances with a valid certificate and password that is configured in app-config-overrides.json.

Developers can either configure the OMS DTK instance, or development or QA cloud instance as a remote server.

  • hostName: The hostname or IP address of the remote server. Supports string value only.
  • port: Indicates the port number of the remote server. Supports numeric value only.
  • https: Indicates whether the HTTPS protocol is used in the remote server. Supports only boolean value.
  • -options: This object is mandatory when a remote server uses the HTTPS protocol.
  • options.pfx: The path of the p12 certificate.

    For more information about generating and downloading the client certificate, see Generating client certificates.

  • options.passphrase: The password of the certificate.
Configure these attributes only in the <store-temp>/app-config-overrides.json file.		 
serveAllAppsFromLocal: true|false
 Indicates whether all the angular applications that are specified in <store-temp>/app-config.json and <store-temp>/app-config-overrides.json must be started and served from a local instance. When this flag is set to true, the useRemote flag that is configured for an individual angular application is ignored. This flag supports only the boolean value, and must be configured only in the <store-temp>/app-config-overrides.json file. 
"routes":{
   ...
   "login":{
      "useRemote":"true|false "devServerConfig"":{
         "port":4200,
         "contextRoot":"login"
      }
   },
   ...
}
 Contains the list of single-spa enabled angular application configurations. Each application configuration includes the following properties:
  • port: Port number where the angular application is served locally. Supports only numeric value.
  • contextRoot: Specifies the context root of the angular application. Supports only string value.
  • useRemote: Flag to indicate whether the application must be served from a remote or local server. Supports only boolean values.
To serve the application-provided angular application from a remote server, define the following configuration in the <store-temp>/app-config-overrides.json file. Ensure that you copy the exact application name.
routes: {
"login": {
  "useRemote": true
}
}

The following table provides the list of application-provided single-spa enabled angular application details:

Table 2. Application-provided routes or micro-frontend applications configured in app-config.json
Application name Description
app-shell Initializes the store application with all the configuration data that is needed for its functioning. The app-shell is loaded in a headless mode and is not visible in the UI.

You cannot customize this application.
nav-bar nav-bar
login Provides the login capability.
home Provides the home page capability, which displays portlets for different persona's.
orders Provides capability that is related to a sales order entity such as order list, order summary, order capture, and order customer appeasement. The entry points are global order search, find orders portlet, and quick checkout portlet.
returns Provides sales order returns capability. The entry point is returns portlet.
customer-profile Provides capability to view customer search results and customer profile details. The entry point is global customer search and find customer portlet.
backroom-pick Provides the pick order capability for Sterling Store Inventory Management (SIM)-enabled stores. The entry point is pick order portlet.
shipment-backroom-pick Provides the shipment-based backroom pick order capability for Store Inventory Management-disabled stores. The entry point is pick order portlet.
batch-pick Provides the batch pick capability for Store Inventory Management-enabled stores. The entry point is pick order portlet.
shipment-batch-pick Provides shipment-based batch pick capability for Store Inventory Management-disabled stores. The entry point is pick order portlet.
pack-order Provides the pack order capability. The entry point is pack order portlet.
customer-pickup Provides the customer pickup capability. The entry point is customer-pickup portlet.
ship-packages Provides ship orders capability. The entry point is ship orders portlet.
shipment-list-summary Provides shipment list and shipment summary capability. The entry point is global shipment search and find shipments portlet.
cycle-count Provides the cycle count capability. The entry point to this application is from cycle count portlet.
lookup-inventory Provides the lookup inventory capability. The entry point is from lookup inventory portlet.
move-inventory Provides the move inventory capability. The entry point to this application is from move inventory portlet.
putaway-inventory Provides the putaway inventory capability. The entry point is from putaway inventory portlet.
transfer-inventory Provides the transfer inventory capability, and the entry point is from transfer inventory portlet.
configurations Helps in configuring locations in a store and is opened from the application menu by using the Configurations menu option.