build.md (c2f8f34e19ef7b9987538e8c2624e629b5203c17) build.md (7385e139b0c9efca7430458cee982e63e282f4ae)
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)

--- 12 unchanged lines hidden (view full) ---

21
22```
23NODE_ENV=production
24VUE_APP_ENV_NAME=ibm
25```
26
27## Store
28
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)

--- 12 unchanged lines hidden (view full) ---

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:::
29:::tip [Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain
30the application's API calls. :::
33
341. If making customizations to the default store, add `CUSTOM_STORE=true` key
35 value pair to the new .env file.
31
321. If making customizations to the default store, add `CUSTOM_STORE=true` key
33 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 :::
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. :::
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
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
61:::tip
62[Vue Router](https://router.vuejs.org/guide/) determines which pages are
63accessible in the UI.
64:::
56:::tip [Vue Router](https://router.vuejs.org/guide/) determines which pages are
57accessible in the UI. :::
65
661. If making customizations to the default router, add `CUSTOM_ROUTER=true` key
67 value pair to the new .env file.
58
591. If making customizations to the default router, add `CUSTOM_ROUTER=true` key
60 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 :::
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. :::
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.
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.
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
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
95 `src/components/AppNavigation/AppNavigation.vue` will resolve to this new
82 `src/components/AppNavigation/AppNavigation.vue` will resolve to this new
96 file.
97 :::
83 file. :::
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/)
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/)
109allows for easy visual customizations.
110:::
95allows for easy visual customizations. :::
111
1121. If making customizations to the default styles, add `CUSTOM_STYLES=true` key
113 value pair to the new .env file.
96
971. If making customizations to the default styles, add `CUSTOM_STYLES=true` key
98 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.
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.
119 :::
102 :::
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).
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).
125
126Example for adding custom colors
127
128`src/env/assets/styles/_ibm.scss`
129
130```
131// Custom theme colors
132

--- 7 unchanged lines hidden (view full) ---

140 `env.development.local` file.
1412. Use serve script
142 ```
143 npm run serve
144 ```
145
146## Production build
147
109
110Example for adding custom colors
111
112`src/env/assets/styles/_ibm.scss`
113
114```
115// Custom theme colors
116

--- 7 unchanged lines hidden (view full) ---

124 `env.development.local` file.
1252. Use serve script
126 ```
127 npm run serve
128 ```
129
130## Production build
131
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).
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).
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```
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```