Migrating new Order Hub applications using a monorepo

Using an Angular monorepo strategy uses Lerna to host several applications in a single repository. This setup provides you with the means to reuse the code, share between applications without having to duplicate code or create library repositories and smaller builds per route, which saves you time. The monorepo strategy is used by all IBM® provided Order Hub repositories. This strategy provides you with a clean customization approach where you can customize routes in an existing IBM repository without taking over all unchanged routes.

About this task

This procedure migrates your new applications to a new monorepo in the next-generation Order Hub environment. This schematic creates a new monorepo to hold multiple projects for your new applications by using Lerna and Single-Spa.

Procedure

  1. Extract the next-generation Order Hub code. For more information, see Getting started with customizing next-generation Order Hub.
    Note: The version parameter for the om-compose.sh extract-orderhub-code command must be oms to extract the next-generation Order Hub code. The version parameter omoc is not applicable to next-generation Order Hub.
  2. Open a console and go to the next-generation Order Hub code directory. The default location is devtoolkit_docker/orderhub-code.
  3. To bypass the SSL verification for interactions with registries, set strict-ssl to false by running the following command. 
    npm config set "strict-ssl" false
  4. Reinstall the latest version of @buc/schematics to access the IBM-provided schematics by running the following commands.

npm uninstall -g @buc/schematics
npm install -g ./lib/buc/schematics/schematics-v5latest.tgz

  1. Create a folder for your new application. The name of the folder is the module name. Copy the app-config.json file that describes the routes in the module into the folder from the existing customization.
  2. In the console, go to the folder that you created.
  3. Create a workspace and initialize a new Angular application by running the following command.

ng new --collection=@buc/schematics \
--app-config-json=<app-config.json-file-name> \
--module-short-name=<short-name-for-the-module> \
--prefix=<selector-prefix> \
--mode=on-prem
Note: The ng new command requires the --mode=on-prem parameter.
The schematic supports the following options.
--skip-git
This option does not initialize a GitHub repository. The default is false.
--commit
This option includes the initial GitHub repository commit information. The default is true.
--app-config-json
These options are required. Use the app-config.json file that you previously created.
--module-short-name
The short name for the module. If the module name has dashes, then the short name must be the text after the last dash. For example, if the module name is buc-app-settings, the module short name must be settings.
--prefix
The HTML selector to use for generated components. The default is buc.
--shared-library-name
The name of the shared library. The default name is <module-short-name>-shared. The package name is @<prefix>/<module-short-name>/-shared.
--generate-root-config
Indicates whether to generate a root-config router project. The default is true.
--skip-install
Indicates whether to install packages. The default is false.
--mode
Set this option to on-prem to generate code that is applicable for next-generation Order Hub.

See the following example.

ng new --collection=@buc/schematics  --app-config-json=app-config.json
      --module-short-name=monorepo  --prefix=monorepo --mode=on-prem
After the command completes, a Packages installed successfully. message is displayed.
Note: If you encounter an error similar to the following message, you can safely ignore the error. These errors do not affect the icons that are used by next-generation Order Hub.
Error: Failed to compile entry-point @carbon/icons-angular/

  1. Copy the angular.json file from the existing customization.

Note: Do not copy the overrides.json or the module package.json files from the existing customization.

  1. For each route, copy the src/app and src/assets folders and any other custom code from the existing customization.

Note: Do not copy the src/environments folder from the existing customization.
Note: Do not copy the route package.json file from the existing customization.

  1. If next-generation Order Hub containers are not currently running, go to the devtoolkit_docker/compose directory and run the following command.

./om-compose.sh start orderhub

  1. Create the local development version of the features.json file. For information, see Creating the features.json files.
  2. To test your new application locally, copy the features.json file into the om-orderhub-base container by running the following commands.

docker exec om-orderhub-base bash -c 'mkdir -p /opt/app-root/src/shell-ui/assets/custom'
docker cp <orderhub-code>/shell-ui/assets/dev/. om-orderhub-base:/opt/app-root/src/shell-ui/assets/custom/

  1. Start the server by entering the following command. 

yarn start-app
Note: You see the following message.
"** Angular Live Development Server is listening on localhost:<port>, 
open your browser on https://localhost:<port>/<module>/<route> **"
You can ignore this message.
Note: If you encounter an error similar to the following message, increase the heap size before you start the new application.
Error command failed with exist code 134.
lerna ERR! yarn run start .... exited 134
Run the following command and then start the new application.
  • Windows CMD prompt: 
    SET NODE_OPTIONS=--max_old_space_size=8048
  • Bash/Git Bash: 
    export NODE_OPTIONS=--max_old_space_size=8048
  • Powershell: 
    $Env:NODE_OPTIONS=--max_old_space_size=8048
If you need to stop the server, stop the server job and run the yarn stop-app command to verify that everything is stopped properly.

  1. To accept the self-signed certificate in the web browser, in a browser, open a tab to https://localhost:9300 and accept the certificate. The port 9300 is the value that is used in devServerConfig in the app-config.json file.

Note: To accept the certificate, it is now https://localhost:9300 instead of https://bucgenerichost:9300.

  1. Start next-generation Order Hub by opening a tab in a browser to https://localhost:7443/order-management. The default port is 7443. If you set the OH_BASE_HTTPS_PORT property in the devtoolkit_docker/compose/om-compose.properties file, use that port number.
  2. Click your new menu item in the left menu navigation.

What to do next

Prepare for deployment, then build, test, and deploy your customizations. For more information , see Deployment process.