1# Build Customization 2 3This document provides instructions for how to add environment specific 4modifications to the Web UI. 5 6- [Setup](#setup) 7- [Store](#store) 8- [Router](#router) 9- [App Navigation](#app-navigation) 10- [Theming](#theming) 11- [Local development](#local-development) 12- [Production build](#production-build) 13 14## Setup 15 161. Create a `.env.<ENV_NAME>` file in the project root 172. Add `NODE_ENV=production` key value pair in the file 183. Add `VUE_APP_ENV_NAME` key with the value set to the new environment name 19 20Example `.env.ibm`: 21 22``` 23NODE_ENV=production 24VUE_APP_ENV_NAME=ibm 25``` 26 27## Store 28 29:::tip 30[Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain the 31application's API calls. 32::: 33 341. If making customizations to the default store, add `CUSTOM_STORE=true` key 35 value pair to the new .env file. 362. Create a `<ENV_NAME>.js` file in `src/env/store` 37 :::danger 38 The filename needs to match the `VUE_APP_ENV_NAME` value defined in the 39 .env file. The store import in `src/main.js` will resolve to this new 40 file. 41 ::: 423. Import the base store 434. Import environment specific store modules 445. Use the [Vuex](https://vuex.vuejs.org/api/#registermodule) `registerModule` 45 and `unregisterModule` instance methods to add/remove store modules 466. Add default export 47 48Example `src/env/store/ibm.js`: 49 50``` 51import store from '@/store; //@ aliases to src directory 52import HmcStore from './Hmc/HmcStore'; 53 54store.registerModule('hmc', HmcStore); 55 56export default store; 57``` 58 59## Router 60 61:::tip 62[Vue Router](https://router.vuejs.org/guide/) determines which pages are 63accessible in the UI. 64::: 65 661. If making customizations to the default router, add `CUSTOM_ROUTER=true` key 67 value pair to the new .env file. 682. Create a `<ENV_NAME>.js` file in `src/env/router` 69 :::danger 70 The filename needs to match the `VUE_APP_ENV_NAME` value defined in the 71 .env file. The routes import in `src/router/index.js` will resolve to this 72 new file. 73 ::: 743. Define new [routes](https://router.vuejs.org/api/#routes). 75 :::tip 76 Use static imports (over lazy-loading routes) to avoid creating separate 77 JS chunks. Static imports also helps to keep the total build size down. 78 ::: 794. Add default export 80 81## App navigation 82 83The Vue Router definition is closely tied to the app navigation but should be 84configured separately. The Vue Router is responsible for defining the 85application routes which is not always the same as what is visible in the app 86navigation. This configuration will make customizations to the rendered markup 87in src/components/AppNavigation/AppNavigation.vue. 88 891. If making customizations to the app navigation, add `CUSTOM_APP_NAV=true` key 90 value pair to the new .env file. 912. Create a `<ENV_NAME>.js` file in `src/env/components/AppNavigation` 92 :::danger 93 The filename needs to match the `VUE_APP_ENV_NAME` value defined in the 94 .env file. The AppNavigationMixin import in 95 `src/components/AppNavigation/AppNavigation.vue` will resolve to this new 96 file. 97 ::: 983. Your custom mixin should follow a very similar structure to the default 99 AppNavigationMixin.js file. It should include a data property named 100 `navigationItems` that should be an array of of navigation objects. Each 101 navigation object should have an `id` and `label` property defined. 102 Optionally it can include `icon`, `route`, or `children` properties. 1034. Add default export 104 105## Theming 106 107:::tip 108[Bootstrap theming](https://getbootstrap.com/docs/4.5/getting-started/theming/) 109allows for easy visual customizations. 110::: 111 1121. If making customizations to the default styles, add `CUSTOM_STYLES=true` key 113 value pair to the new .env file. 1142. Create a `_<ENV_NAME>.scss` partial in `src/env/assets/styles` 115 :::danger 116 The filename needs to match the `VUE_APP_ENV_NAME` value defined in the 117 .env file. The webpack sass loader will attempt to import a file with this 118 name. 119 ::: 1203. Add style customizations. Refer to [bootstrap documentation](https://getbootstrap.com/docs/4.5/getting-started/theming/) 121 for details about [color 122 overrides](https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults) 123 and [other customizable 124 options](https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options). 125 126Example for adding custom colors 127 128`src/env/assets/styles/_ibm.scss` 129 130``` 131// Custom theme colors 132 133$primary: rebeccapurple; 134$success: lime; 135``` 136 137## Local development 138 1391. Add the same `VUE_APP_ENV_NAME` key value pair to your 140 `env.development.local` file. 1412. Use serve script 142 ``` 143 npm run serve 144 ``` 145 146## Production build 147 148Run npm build script with vue-cli `--mode` [option 149flag](https://cli.vuejs.org/guide/mode-and-env.html#modes). This requires 150[corresponding .env file to exist](#setup). 151 152``` 153npm run build -- --mode ibm 154``` 155 156**OR** 157 158pass env variable directly to script 159 160``` 161VUE_APP_ENV_NAME=ibm npm run build 162``` 163