1c2f8f34eSDerick Montague# Build Customization 2c2f8f34eSDerick Montague 3c2f8f34eSDerick MontagueThis document provides instructions for how to add environment specific 4c2f8f34eSDerick Montaguemodifications to the Web UI. 5c2f8f34eSDerick Montague 6c2f8f34eSDerick Montague- [Setup](#setup) 7c2f8f34eSDerick Montague- [Store](#store) 8c2f8f34eSDerick Montague- [Router](#router) 9c2f8f34eSDerick Montague- [App Navigation](#app-navigation) 10c2f8f34eSDerick Montague- [Theming](#theming) 11c2f8f34eSDerick Montague- [Local development](#local-development) 12c2f8f34eSDerick Montague- [Production build](#production-build) 13c2f8f34eSDerick Montague 14c2f8f34eSDerick Montague## Setup 15c2f8f34eSDerick Montague 16c2f8f34eSDerick Montague1. Create a `.env.<ENV_NAME>` file in the project root 17c2f8f34eSDerick Montague2. Add `NODE_ENV=production` key value pair in the file 18c2f8f34eSDerick Montague3. Add `VUE_APP_ENV_NAME` key with the value set to the new environment name 19c2f8f34eSDerick Montague 20c2f8f34eSDerick MontagueExample `.env.ibm`: 21c2f8f34eSDerick Montague 22c2f8f34eSDerick Montague``` 23c2f8f34eSDerick MontagueNODE_ENV=production 24c2f8f34eSDerick MontagueVUE_APP_ENV_NAME=ibm 25c2f8f34eSDerick Montague``` 26c2f8f34eSDerick Montague 27c2f8f34eSDerick Montague## Store 28c2f8f34eSDerick Montague 29*7385e139SPatrick Williams:::tip [Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain 30*7385e139SPatrick Williamsthe application's API calls. ::: 31c2f8f34eSDerick Montague 32c2f8f34eSDerick Montague1. If making customizations to the default store, add `CUSTOM_STORE=true` key 33c2f8f34eSDerick Montague value pair to the new .env file. 34*7385e139SPatrick Williams2. Create a `<ENV_NAME>.js` file in `src/env/store` :::danger The filename needs 35*7385e139SPatrick Williams to match the `VUE_APP_ENV_NAME` value defined in the .env file. The store 36*7385e139SPatrick Williams import in `src/main.js` will resolve to this new file. ::: 37c2f8f34eSDerick Montague3. Import the base store 38c2f8f34eSDerick Montague4. Import environment specific store modules 39c2f8f34eSDerick Montague5. Use the [Vuex](https://vuex.vuejs.org/api/#registermodule) `registerModule` 40c2f8f34eSDerick Montague and `unregisterModule` instance methods to add/remove store modules 41c2f8f34eSDerick Montague6. Add default export 42c2f8f34eSDerick Montague 43c2f8f34eSDerick MontagueExample `src/env/store/ibm.js`: 44c2f8f34eSDerick Montague 45c2f8f34eSDerick Montague``` 46c2f8f34eSDerick Montagueimport store from '@/store; //@ aliases to src directory 47c2f8f34eSDerick Montagueimport HmcStore from './Hmc/HmcStore'; 48c2f8f34eSDerick Montague 49c2f8f34eSDerick Montaguestore.registerModule('hmc', HmcStore); 50c2f8f34eSDerick Montague 51c2f8f34eSDerick Montagueexport default store; 52c2f8f34eSDerick Montague``` 53c2f8f34eSDerick Montague 54c2f8f34eSDerick Montague## Router 55c2f8f34eSDerick Montague 56*7385e139SPatrick Williams:::tip [Vue Router](https://router.vuejs.org/guide/) determines which pages are 57*7385e139SPatrick Williamsaccessible in the UI. ::: 58c2f8f34eSDerick Montague 59c2f8f34eSDerick Montague1. If making customizations to the default router, add `CUSTOM_ROUTER=true` key 60c2f8f34eSDerick Montague value pair to the new .env file. 61*7385e139SPatrick Williams2. Create a `<ENV_NAME>.js` file in `src/env/router` :::danger The filename 62*7385e139SPatrick Williams needs to match the `VUE_APP_ENV_NAME` value defined in the .env file. The 63*7385e139SPatrick Williams routes import in `src/router/index.js` will resolve to this new file. ::: 64*7385e139SPatrick Williams3. Define new [routes](https://router.vuejs.org/api/#routes). :::tip Use static 65*7385e139SPatrick Williams imports (over lazy-loading routes) to avoid creating separate JS chunks. 66*7385e139SPatrick Williams Static imports also helps to keep the total build size down. ::: 67c2f8f34eSDerick Montague4. Add default export 68c2f8f34eSDerick Montague 69c2f8f34eSDerick Montague## App navigation 70c2f8f34eSDerick Montague 71c2f8f34eSDerick MontagueThe Vue Router definition is closely tied to the app navigation but should be 72c2f8f34eSDerick Montagueconfigured separately. The Vue Router is responsible for defining the 73c2f8f34eSDerick Montagueapplication routes which is not always the same as what is visible in the app 74c2f8f34eSDerick Montaguenavigation. This configuration will make customizations to the rendered markup 75c2f8f34eSDerick Montaguein src/components/AppNavigation/AppNavigation.vue. 76c2f8f34eSDerick Montague 77c2f8f34eSDerick Montague1. If making customizations to the app navigation, add `CUSTOM_APP_NAV=true` key 78c2f8f34eSDerick Montague value pair to the new .env file. 79*7385e139SPatrick Williams2. Create a `<ENV_NAME>.js` file in `src/env/components/AppNavigation` :::danger 80*7385e139SPatrick Williams The filename needs to match the `VUE_APP_ENV_NAME` value defined in the .env 81*7385e139SPatrick Williams file. The AppNavigationMixin import in 82c2f8f34eSDerick Montague `src/components/AppNavigation/AppNavigation.vue` will resolve to this new 83*7385e139SPatrick Williams file. ::: 84c2f8f34eSDerick Montague3. Your custom mixin should follow a very similar structure to the default 85c2f8f34eSDerick Montague AppNavigationMixin.js file. It should include a data property named 86c2f8f34eSDerick Montague `navigationItems` that should be an array of of navigation objects. Each 87c2f8f34eSDerick Montague navigation object should have an `id` and `label` property defined. 88c2f8f34eSDerick Montague Optionally it can include `icon`, `route`, or `children` properties. 89c2f8f34eSDerick Montague4. Add default export 90c2f8f34eSDerick Montague 91c2f8f34eSDerick Montague## Theming 92c2f8f34eSDerick Montague 93c2f8f34eSDerick Montague:::tip 94c2f8f34eSDerick Montague[Bootstrap theming](https://getbootstrap.com/docs/4.5/getting-started/theming/) 95*7385e139SPatrick Williamsallows for easy visual customizations. ::: 96c2f8f34eSDerick Montague 97c2f8f34eSDerick Montague1. If making customizations to the default styles, add `CUSTOM_STYLES=true` key 98c2f8f34eSDerick Montague value pair to the new .env file. 99*7385e139SPatrick Williams2. Create a `_<ENV_NAME>.scss` partial in `src/env/assets/styles` :::danger The 100*7385e139SPatrick Williams filename needs to match the `VUE_APP_ENV_NAME` value defined in the .env 101*7385e139SPatrick Williams file. The webpack sass loader will attempt to import a file with this name. 102c2f8f34eSDerick Montague ::: 103*7385e139SPatrick Williams3. Add style customizations. Refer to 104*7385e139SPatrick Williams [bootstrap documentation](https://getbootstrap.com/docs/4.5/getting-started/theming/) 105*7385e139SPatrick Williams for details about 106*7385e139SPatrick Williams [color overrides](https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults) 107*7385e139SPatrick Williams and 108*7385e139SPatrick Williams [other customizable options](https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options). 109c2f8f34eSDerick Montague 110c2f8f34eSDerick MontagueExample for adding custom colors 111c2f8f34eSDerick Montague 112c2f8f34eSDerick Montague`src/env/assets/styles/_ibm.scss` 113c2f8f34eSDerick Montague 114c2f8f34eSDerick Montague``` 115c2f8f34eSDerick Montague// Custom theme colors 116c2f8f34eSDerick Montague 117c2f8f34eSDerick Montague$primary: rebeccapurple; 118c2f8f34eSDerick Montague$success: lime; 119c2f8f34eSDerick Montague``` 120c2f8f34eSDerick Montague 121c2f8f34eSDerick Montague## Local development 122c2f8f34eSDerick Montague 123c2f8f34eSDerick Montague1. Add the same `VUE_APP_ENV_NAME` key value pair to your 124c2f8f34eSDerick Montague `env.development.local` file. 125c2f8f34eSDerick Montague2. Use serve script 126c2f8f34eSDerick Montague ``` 127c2f8f34eSDerick Montague npm run serve 128c2f8f34eSDerick Montague ``` 129c2f8f34eSDerick Montague 130c2f8f34eSDerick Montague## Production build 131c2f8f34eSDerick Montague 132*7385e139SPatrick WilliamsRun npm build script with vue-cli `--mode` 133*7385e139SPatrick Williams[option flag](https://cli.vuejs.org/guide/mode-and-env.html#modes). This 134*7385e139SPatrick Williamsrequires [corresponding .env file to exist](#setup). 135c2f8f34eSDerick Montague 136c2f8f34eSDerick Montague``` 137c2f8f34eSDerick Montaguenpm run build -- --mode ibm 138c2f8f34eSDerick Montague``` 139c2f8f34eSDerick Montague 140c2f8f34eSDerick Montague**OR** 141c2f8f34eSDerick Montague 142c2f8f34eSDerick Montaguepass env variable directly to script 143c2f8f34eSDerick Montague 144c2f8f34eSDerick Montague``` 145c2f8f34eSDerick MontagueVUE_APP_ENV_NAME=ibm npm run build 146c2f8f34eSDerick Montague``` 147