|
1 | 1 | # Topcoder Frame Single-Spa Application (mfe-core) |
2 | 2 |
|
3 | | -This is the mfe-core [single-spa](https://single-spa.js.org/) application which loads all other Topcoder micro applications. |
4 | | -It always loads **Topcoder Navbar Microapp** which show the top navigation and handles authorization and loads other microapps depend on the current URL. |
| 3 | +This is the mfe-core [single-spa](https://single-spa.js.org/) application which loads all other Topcoder micro-frontend (MFE) applications. |
| 4 | +It always loads the **Topcoder Header Microapp** which provides the top-level navigation, handles authorization, and loads other microapps depending on the current URL. |
5 | 5 |
|
6 | 6 | ## Overview |
7 | 7 |
|
8 | 8 | Topcoder Single Spa consist of 3 main components: |
9 | 9 |
|
10 | | -- This frame application which is `mfe-core` [single-spa](https://single-spa.js.org/) application. The only function of this application is to register other micro applications to load. |
11 | | -- **Topcoder Navbar Microapp** - micro application which is always loaded by the frame application and shows top navigation bar and handles user authorization. |
| 10 | +- This frame application, `mfe-core`, which is a [single-spa](https://single-spa.js.org/) application. The only function of this application is to register other micro applications to load. |
| 11 | +- **Topcoder Header Microapp** - micro application which is always loaded by the frame application and shows the top-level navigation bar and handles user authorization. |
12 | 12 | - Any other micro application can be loaded as main content of the overall application. |
13 | 13 |
|
14 | 14 | ## Requirements |
15 | 15 |
|
16 | 16 | Use the node version manager [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) to easily and safely manage the required version of NodeJS (aka, node). Download and install it per the instructions for your development operating system. Installing a version of node via `nvm` will also install `npm`. |
17 | 17 |
|
18 | | -You can configure your command shell to automatically use the correct version of node based on the existence of a `.nvmrc` file in the root of the project directory. See [the nvm Github README](https://github.com/nvm-sh/nvm/blob/master/README.md#deeper-shell-integration) for more information on setting this up. |
| 18 | +Once nvm is installed, run: |
| 19 | +``` |
| 20 | +$ nvm install <insert node version> |
| 21 | +``` |
| 22 | + |
| 23 | +>Note: the node version required at the time of this writing is `10.22.1` |
| 24 | +
|
| 25 | +At the root of the project directory you'll notice a file called `.nvmrc` which specifies the node version used by the project. The command `nvm use` will use the version specified in the file if no version is supplied on the command line. |
| 26 | +See [the nvm Github README](https://github.com/nvm-sh/nvm/blob/master/README.md#nvmrc) for more information on setting this up. |
19 | 27 |
|
20 | 28 | You can verify the versions of `nvm`, `node`, and `npm` using the commands below. |
21 | | -| Command | Version | |
22 | | -| -------------------- | ---------------------- | |
23 | | -| `$ npm -v` | 6.14.12 | |
24 | | -| `$ node -v` | v10.22.1 | |
25 | | -| `$ nvm --version` | 0.39.1 | |
26 | | -| `$ nvm current` | v10.22.1 | |
| 29 | +| Command | Version | |
| 30 | +| ----------------- | -------- | |
| 31 | +| `$ npm -v` | 6.14.12 | |
| 32 | +| `$ node -v` | v10.22.1 | |
| 33 | +| `$ nvm --version` | 0.39.1 | |
| 34 | +| `$ nvm current` | v10.22.1 | |
27 | 35 |
|
28 | 36 | ## Local Development Setup |
29 | 37 |
|
30 | | -### IDE Configuration |
| 38 | +### IDE |
31 | 39 |
|
32 | | -Use the [VS Code](https://code.visualstudio.com/download) IDE for MFE development. Once installed, install the `TSLint` extension to provide Typescript linting capability. The linter will use the settings and rules as defined in the `tslint.config` file in the project's root directory. |
| 40 | +Use the [VS Code](https://code.visualstudio.com/download) IDE for MFE development. |
33 | 41 |
|
34 | | -Once the extension is installed you need to configure VS Code to use it correctly. #TODO |
| 42 | +### Hosting |
| 43 | +You will need to add the following line to your hosts file. The hosts file is normally located at `/etc/hosts` (Mac). Do not overwrite the existing localhost entry also pointing to 127.0.0.1 |
35 | 44 |
|
36 | | -Also, in order to use tslint from the command line, install it globally via `npm`: |
37 | 45 | ``` |
38 | | -$ npm i -g tslint |
| 46 | +127.0.0.1 local.topcoder-dev.com |
39 | 47 | ``` |
| 48 | + |
| 49 | +The MFE can run in a non-ssl environment, but auth0 will complain and throw errors. In order to bypass this, you will need to install [local-ssl-proxy](https://www.npmjs.com/package/local-ssl-proxy) to run the site in ssl. The following command will install it globally: |
| 50 | +``` |
| 51 | +$ npm i -g local-ssl-proxy |
| 52 | +``` |
| 53 | + |
40 | 54 | ### Terminal Configuration |
41 | 55 |
|
42 | | -The MFE Frame needs to run separate local server and client processes, each one in a separate terminal session. The navbar also needs to run its server in a terminal, along with the `local-ssl-proxy` server that will allow you to use *https* endpoints locally. Finally, each of the other micro front-end applications you want to run will also each run in their own terminal session. |
| 56 | +The MFE Core Frame needs to run separate local server and client processes, each one in a separate terminal session. The navbar also needs to run its server in a terminal, along with the `local-ssl-proxy` server that will allow you to use *https* endpoints locally. Finally, each of the other micro front-end applications you want to run will also each run in their own terminal session. |
43 | 57 |
|
44 | 58 | When developing one of the micro front-end applications you will therefore have 5 terminal sessions running at the same time: |
45 | 59 |
|
46 | | -- `mfe-frame` server |
47 | | -- `mfe-frame` client |
48 | | -- `navbar` application |
| 60 | +- `mfe-core` server |
| 61 | +- `mfe-core` client |
| 62 | +- `mfe-header` application |
49 | 63 | - `local-ssl-proxy` server |
50 | | -- the micro front-end app you're developing |
| 64 | +- the MFE app you're developing |
51 | 65 |
|
52 | 66 | Given this complexity, it is recommended that you use a tool like [iTerm2](https://iterm2.com) (on Mac) or an equivalent terminal shell on Windows to make terminal management simpler. iTerm2 allows you to setup a pre-defined window layout of terminal sessions, including the directory in which the session starts. With this setup, along with simple shell scripts in each project that configure and start the environment (#TODO), will allow you to get your development environment up and running quickly and easily. |
53 | 67 |
|
| 68 | +### Linting |
| 69 | +We use linting to enforce standardization. Please make sure all lint rules pass before creating PRs. |
| 70 | + |
| 71 | +Use the following command to check for lint errors: |
| 72 | +``` |
| 73 | +$ npm run lint |
| 74 | +``` |
| 75 | + |
| 76 | +## Git |
| 77 | +### Branching |
| 78 | +When working on Jira tickets, we link associated Git PRs and branches to the tickets. Use the following naming convention for branches: |
| 79 | + |
| 80 | +`[TICKET #]_short-description` |
| 81 | + |
| 82 | +e.g.: `PROD-1516_work-issue` |
| 83 | + |
| 84 | +### Commits |
| 85 | +We use [Smart Commits](https://bigbrassband.com/git-integration-for-jira/documentation/smart-commits.html#bbb-nav-basic-examples) to link comments and time tracking to tickets. You would enter the following as your commit message: |
| 86 | + |
| 87 | +`[TICKET #] #comment <commit message> #time <jira-formatted time>` |
| 88 | + |
| 89 | +e.g.: `PLAT-001 #comment adding readme notes #time 45m` |
| 90 | + |
| 91 | + |
54 | 92 | ## Application Configuration |
55 | 93 |
|
56 | 94 | This `mfe-core` app has 2 types of configs: |
|
0 commit comments