diff options
Diffstat (limited to 'docs/customization/build.md')
-rw-r--r-- | docs/customization/build.md | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/docs/customization/build.md b/docs/customization/build.md new file mode 100644 index 00000000..b10fd9db --- /dev/null +++ b/docs/customization/build.md @@ -0,0 +1,162 @@ +# Build Customization + +This document provides instructions for how to add environment specific +modifications to the Web UI. + +- [Setup](#setup) +- [Store](#store) +- [Router](#router) +- [App Navigation](#app-navigation) +- [Theming](#theming) +- [Local development](#local-development) +- [Production build](#production-build) + +## Setup + +1. Create a `.env.<ENV_NAME>` file in the project root +2. Add `NODE_ENV=production` key value pair in the file +3. Add `VUE_APP_ENV_NAME` key with the value set to the new environment name + +Example `.env.ibm`: + +``` +NODE_ENV=production +VUE_APP_ENV_NAME=ibm +``` + +## Store + +:::tip +[Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain the +application's API calls. +::: + +1. If making customizations to the default store, add `CUSTOM_STORE=true` key + value pair to the new .env file. +2. Create a `<ENV_NAME>.js` file in `src/env/store` + :::danger + The filename needs to match the `VUE_APP_ENV_NAME` value defined in the + .env file. The store import in `src/main.js` will resolve to this new + file. + ::: +3. Import the base store +4. Import environment specific store modules +5. Use the [Vuex](https://vuex.vuejs.org/api/#registermodule) `registerModule` + and `unregisterModule` instance methods to add/remove store modules +6. Add default export + +Example `src/env/store/ibm.js`: + +``` +import store from '@/store; //@ aliases to src directory +import HmcStore from './Hmc/HmcStore'; + +store.registerModule('hmc', HmcStore); + +export default store; +``` + +## Router + +:::tip +[Vue Router](https://router.vuejs.org/guide/) determines which pages are +accessible in the UI. +::: + +1. If making customizations to the default router, add `CUSTOM_ROUTER=true` key + value pair to the new .env file. +2. Create a `<ENV_NAME>.js` file in `src/env/router` + :::danger + The filename needs to match the `VUE_APP_ENV_NAME` value defined in the + .env file. The routes import in `src/router/index.js` will resolve to this + new file. + ::: +3. Define new [routes](https://router.vuejs.org/api/#routes). + :::tip + Use static imports (over lazy-loading routes) to avoid creating separate + JS chunks. Static imports also helps to keep the total build size down. + ::: +4. Add default export + +## App navigation + +The Vue Router definition is closely tied to the app navigation but should be +configured separately. The Vue Router is responsible for defining the +application routes which is not always the same as what is visible in the app +navigation. This configuration will make customizations to the rendered markup +in src/components/AppNavigation/AppNavigation.vue. + +1. If making customizations to the app navigation, add `CUSTOM_APP_NAV=true` key + value pair to the new .env file. +2. Create a `<ENV_NAME>.js` file in `src/env/components/AppNavigation` + :::danger + The filename needs to match the `VUE_APP_ENV_NAME` value defined in the + .env file. The AppNavigationMixin import in + `src/components/AppNavigation/AppNavigation.vue` will resolve to this new + file. + ::: +3. Your custom mixin should follow a very similar structure to the default + AppNavigationMixin.js file. It should include a data property named + `navigationItems` that should be an array of of navigation objects. Each + navigation object should have an `id` and `label` property defined. + Optionally it can include `icon`, `route`, or `children` properties. +4. Add default export + +## Theming + +:::tip +[Bootstrap theming](https://getbootstrap.com/docs/4.5/getting-started/theming/) +allows for easy visual customizations. +::: + +1. If making customizations to the default styles, add `CUSTOM_STYLES=true` key + value pair to the new .env file. +2. Create a `_<ENV_NAME>.scss` partial in `src/env/assets/styles` + :::danger + The filename needs to match the `VUE_APP_ENV_NAME` value defined in the + .env file. The webpack sass loader will attempt to import a file with this + name. + ::: +3. Add style customizations. Refer to [bootstrap documentation](https://getbootstrap.com/docs/4.5/getting-started/theming/) + for details about [color + overrides](https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults) + and [other customizable + options](https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options). + +Example for adding custom colors + +`src/env/assets/styles/_ibm.scss` + +``` +// Custom theme colors + +$primary: rebeccapurple; +$success: lime; +``` + +## Local development + +1. Add the same `VUE_APP_ENV_NAME` key value pair to your + `env.development.local` file. +2. Use serve script + ``` + npm run serve + ``` + +## Production build + +Run npm build script with vue-cli `--mode` [option +flag](https://cli.vuejs.org/guide/mode-and-env.html#modes). This requires +[corresponding .env file to exist](#setup). + +``` +npm run build -- --mode ibm +``` + +**OR** + +pass env variable directly to script + +``` +VUE_APP_ENV_NAME=ibm npm run build +``` |