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