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 [Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain
30the application's API calls. :::
31
321. If making customizations to the default store, add `CUSTOM_STORE=true` key
33   value pair to the new .env file.
342. Create a `<ENV_NAME>.js` file in `src/env/store` :::danger The filename needs
35   to match the `VUE_APP_ENV_NAME` value defined in the .env file. The store
36   import in `src/main.js` will resolve to this new file. :::
373. Import the base store
384. Import environment specific store modules
395. Use the [Vuex](https://vuex.vuejs.org/api/#registermodule) `registerModule`
40   and `unregisterModule` instance methods to add/remove store modules
416. Add default export
42
43Example `src/env/store/ibm.js`:
44
45```
46import store from '@/store; //@ aliases to src directory
47import HmcStore from './Hmc/HmcStore';
48
49store.registerModule('hmc', HmcStore);
50
51export default store;
52```
53
54## Router
55
56:::tip [Vue Router](https://router.vuejs.org/guide/) determines which pages are
57accessible in the UI. :::
58
591. If making customizations to the default router, add `CUSTOM_ROUTER=true` key
60   value pair to the new .env file.
612. Create a `<ENV_NAME>.js` file in `src/env/router` :::danger The filename
62   needs to match the `VUE_APP_ENV_NAME` value defined in the .env file. The
63   routes import in `src/router/index.js` will resolve to this new file. :::
643. Define new [routes](https://router.vuejs.org/api/#routes). :::tip Use static
65   imports (over lazy-loading routes) to avoid creating separate JS chunks.
66   Static imports also helps to keep the total build size down. :::
674. Add default export
68
69## App navigation
70
71The Vue Router definition is closely tied to the app navigation but should be
72configured separately. The Vue Router is responsible for defining the
73application routes which is not always the same as what is visible in the app
74navigation. This configuration will make customizations to the rendered markup
75in src/components/AppNavigation/AppNavigation.vue.
76
771. If making customizations to the app navigation, add `CUSTOM_APP_NAV=true` key
78   value pair to the new .env file.
792. Create a `<ENV_NAME>.js` file in `src/env/components/AppNavigation` :::danger
80   The filename needs to match the `VUE_APP_ENV_NAME` value defined in the .env
81   file. The AppNavigationMixin import in
82   `src/components/AppNavigation/AppNavigation.vue` will resolve to this new
83   file. :::
843. Your custom mixin should follow a very similar structure to the default
85   AppNavigationMixin.js file. It should include a data property named
86   `navigationItems` that should be an array of of navigation objects. Each
87   navigation object should have an `id` and `label` property defined.
88   Optionally it can include `icon`, `route`, or `children` properties.
894. Add default export
90
91## Theming
92
93:::tip
94[Bootstrap theming](https://getbootstrap.com/docs/4.5/getting-started/theming/)
95allows for easy visual customizations. :::
96
971. If making customizations to the default styles, add `CUSTOM_STYLES=true` key
98   value pair to the new .env file.
992. Create a `_<ENV_NAME>.scss` partial in `src/env/assets/styles` :::danger The
100   filename needs to match the `VUE_APP_ENV_NAME` value defined in the .env
101   file. The webpack sass loader will attempt to import a file with this name.
102   :::
1033. Add style customizations. Refer to
104   [bootstrap documentation](https://getbootstrap.com/docs/4.5/getting-started/theming/)
105   for details about
106   [color overrides](https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults)
107   and
108   [other customizable options](https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options).
109
110Example for adding custom colors
111
112`src/env/assets/styles/_ibm.scss`
113
114```
115// Custom theme colors
116
117$primary: rebeccapurple;
118$success: lime;
119```
120
121## Local development
122
1231. Add the same `VUE_APP_ENV_NAME` key value pair to your
124   `env.development.local` file.
1252. Use serve script
126   ```
127   npm run serve
128   ```
129
130## Production build
131
132Run npm build script with vue-cli `--mode`
133[option flag](https://cli.vuejs.org/guide/mode-and-env.html#modes). This
134requires [corresponding .env file to exist](#setup).
135
136```
137npm run build -- --mode ibm
138```
139
140**OR**
141
142pass env variable directly to script
143
144```
145VUE_APP_ENV_NAME=ibm npm run build
146```
147