Skip to content

Commit 0c4f108

Browse files
author
Maria Mattlin
committed
PROD-1537 #comment Recreated updates from previous PR on top of the new QA branch #time 10m
1 parent 3c26564 commit 0c4f108

File tree

5 files changed

+379
-22600
lines changed

5 files changed

+379
-22600
lines changed

‎.nvmrc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
16.15.0
1+
10.22.1

‎README.md

+273-13
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,87 @@
11
# Topcoder Self Service Micro Frontend App
22

3-
This is a [single-spa](https://single-spa.js.org/) example React microapp.
3+
This is a [single-spa](https://single-spa.js.org/) React microapp that runs within the `mfe-core` frame application.
44

5-
> NOTE. This application have been configured to be run as child app of a single-spa application. So while this app can be deployed and run independently, we would need some frame [single-spa](https://single-spa.js.org/) which would load it. While technically we can achieve running this app as standalone app it's strongly not recommended by the author of the `single-spa` approch, see this [GitHub Issue](https://github.com/single-spa/single-spa/issues/640) for details.
5+
> **NOTE:** This application has been configured to be run as child app of a single-spa application. So while this app can be deployed and run independently, we would need some frame [single-spa](https://single-spa.js.org/) which would load it. While technically we can achieve running this app as standalone app it's strongly not recommended by the author of the `single-spa` approch, see this [GitHub Issue](https://github.com/single-spa/single-spa/issues/640) for details.
66
7-
## Requirements
7+
>**NOTE:** To successfully run this application, you must also run the two following apps: `mfe-core` & `mfe-header`. Please see their corresponding README's for instructions on running each app.
88
9-
- node - v10.22.1
10-
- npm - v6.14.6
9+
## Local Environment Setup
10+
11+
### IDE
12+
13+
Use the [VS Code](https://code.visualstudio.com/download) IDE for MFE development.
14+
15+
### NVM
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+
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.
27+
28+
You can verify the versions of `nvm`, `node`, and `npm` using the commands below.
29+
| Command | Supported Version |
30+
| ----------------- | -------- |
31+
| `$ npm -v` | 6.14.6 |
32+
| `$ node -v` | v10.22.1 |
33+
| `$ nvm --version` | 0.39.1 |
34+
| `$ nvm current` | v10.22.1 |
35+
36+
### Hosting
37+
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.
38+
39+
```
40+
127.0.0.1 local.topcoder-dev.com
41+
```
42+
43+
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:
44+
```
45+
$ npm i -g local-ssl-proxy
46+
```
47+
48+
### Terminal Configuration
49+
50+
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.
51+
52+
When developing one of the micro front-end applications you will therefore have 5 terminal sessions running at the same time:
53+
54+
- `mfe-core` server
55+
- `mfe-core` client
56+
- `mfe-header` application
57+
- `local-ssl-proxy` server
58+
- the MFE app you're developing
59+
60+
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. This setup, along with simple shell scripts in each project that configure and start the environment, will allow you to get your development environment up and running quickly and easily.
61+
62+
## Git
63+
### Branching
64+
When working on Jira tickets, we link associated Git PRs and branches to the tickets. Use the following naming convention for branches:
65+
66+
`[TICKET #]_short-description`
67+
68+
e.g.: `PROD-1516_work-issue`
69+
70+
### Commits
71+
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:
72+
73+
`[TICKET #] #comment <commit message> #time <jira-formatted time>`
74+
75+
e.g.: `PLAT-001 #comment adding readme notes #time 45m`
1176

1277
## NPM Commands
1378

1479
| Command | Description |
1580
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
1681
| `npm start` | Run server which serves production ready build from `dist` folder |
82+
| `npm start-local` | Run app locally in the `development` mode and `dev` config (calls on `npm run dev`) |
1783
| `npm run dev` | Run app in the `development` mode and `dev` config |
18-
| `npm run dev-https` | Run app in the `development` mode and `dev` config using HTTPS protocol |
19-
| `npm run local` | Run app in the `development` mode and `dev` config |
84+
| `npm run dev-https` | Run app in the `development` mode and `dev` config using HTTPS protocol |
2085
| `npm run prod` | Run app in the `development` mode and `prod` config |
2186
| `npm run build` | Build app for production and puts files to the `dist` folder, default to `development` mode and `dev` config |
2287
| `npm run analyze` | Analyze dependencies sizes and opens report in the browser |
@@ -29,12 +94,21 @@ This is a [single-spa](https://single-spa.js.org/) example React microapp.
2994

3095
## Local Deployment
3196

32-
Inside the project folder run:
97+
To run the app locally, run the following command from the project root `./mfe-customer-work`:
3398

34-
- `nvm use 10.22.1;` - to use npm version: 10.22.1
35-
- `npm i` - install dependencies
36-
- `npm run local` - run app in `development` mode and `dev` config
37-
- This app will be loaded as a normal MFE app, its url is `http://localhost:8519/self-service/topcoder-mfe-customer-work.js` and is configurated in the config file of Self Service App
99+
macOS:
100+
```
101+
$ npm run start-local
102+
```
103+
104+
Windows:
105+
106+
Copy the contents of the Bash script `start-local.sh` and paste them in the Command Prompt.
107+
108+
109+
The Self-Service app should now be available at https://local.topcoder-dev.com/self-service.
110+
111+
>**NOTE:** To successfully run this application, you must also run the two following apps: `mfe-core` & `mfe-header`. Please see their corresponding README's for instructions on running each app.
38112
39113
## Deployment to Production
40114

@@ -44,7 +118,7 @@ Inside the project folder run:
44118

45119
### Deploying to Heroku
46120

47-
Make sure you have [Heroky CLI](https://devcenter.heroku.com/articles/heroku-cli) installed and you have a Heroku account. And then inside the project folder run the next commands:
121+
Make sure you have [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) installed and you have a Heroku account. And then inside the project folder run the next commands:
48122

49123
- If there is not Git repository inited yet, create a repo and commit all the files:
50124

@@ -77,3 +151,189 @@ VALID_ISSUERS=
77151
```
78152

79153
Once the self service app is started, the aggregator api will work as well
154+
155+
## Linting
156+
157+
### Rules
158+
While [TSLint](https://palantir.github.io/tslint/) is technically deprecated in favor of [Typescript ESLint](https://typescript-eslint.io/), TSLint is still far better at linting Typescript files than ESLint. So, for the time being, TSLint will be the primary linter, but ESLint remains configured for JS/X files.
159+
160+
The following command will install TSLint globally:
161+
```
162+
$ npm i -g tslint typescript
163+
```
164+
165+
### Command Line
166+
167+
#### View All Lint Errors
168+
169+
```
170+
$npm run tslint
171+
```
172+
173+
#### Fix All Auto-fixable and View All Non-fixable Lint Errors
174+
175+
```
176+
$ npm run tslint:fix
177+
178+
OR
179+
180+
$ npm run lint (for JS/X files)
181+
```
182+
183+
### VS Code
184+
185+
VS Code has several plugins and settings that make linting easy.
186+
187+
#### Format on Save
188+
189+
The most useful feature is to automatically apply all lint rules any time you save a file.
190+
191+
1) Code → Preferences → Settings
192+
193+
2) Search for “save” to find the setting
194+
- Editor: Code Actions on Save
195+
196+
3) Click the “Edit in settings.json” link
197+
198+
4) Add the following config:
199+
```
200+
{
201+
...
202+
"editor.formatOnSave": true,
203+
"editor.codeActionsOnSave": {
204+
"source.fixAll.tslint": true,
205+
},
206+
}
207+
```
208+
209+
#### TSLint Plugin
210+
211+
Created by Microsoft, this plugin will allow you to see lint errors in the Problems panel.
212+
213+
**WARNING:** Other lint plugins can interfere with TSLint, so it is recommended that you uninstall/disable all other lint plugins (e.g. ESLint, Prettier, etc).
214+
215+
## Styling
216+
217+
We use [Sass](https://sass-lang.com/) for styling, which is a preprocessor scripting language that compiles to CSS and allows for the use of variables, nested rules, mixins, functions, etc.
218+
219+
**Variables** can be used to store any CSS value that you want to reuse throughout your stylesheets. Variables are prefixed with the $ symbol.
220+
221+
e.g. styles.scss
222+
```
223+
$primary-color: #333;
224+
225+
body {
226+
color: $primary-color;
227+
}
228+
```
229+
230+
**Mixins** let you create groups of CSS declarations that you want to reuse throughout your site. You can also pass in values to make your mixin more flexible, and you call them using `@include`.
231+
232+
e.g. styles.scss
233+
```
234+
@mixin theme($theme: DarkGray) {
235+
background: $theme;
236+
color: #fff;
237+
}
238+
239+
.info {
240+
@include theme;
241+
}
242+
.alert {
243+
@include theme($theme: DarkRed);
244+
}
245+
```
246+
247+
Shared stylesheets are located in `src-ts/lib/styles/`. We use variables and mixins for handling padding, colors and breakpoints in the application, among others. To reference these in your SCSS files, simply add the following line at the top of your file.
248+
249+
```
250+
@import '[path to]/lib/styles';
251+
```
252+
253+
### Colors
254+
255+
Colors are defined as variables in `src-ts/lib/styles/_palette.scss`.
256+
257+
### Padding
258+
259+
Padding for various screen sizes are defined as variables in `src-ts/lib/styles/_layout.scss`. This file also contains a mixin called `pagePaddings` that determines the correct padding to use for the current screen size based on breakpoints.
260+
261+
### Breakpoints
262+
263+
Breakpoint mixins are defined in `src-ts/lib/styles/_breakpoints.scss` and can be used to apply different styling based on the screen width.
264+
265+
Here is an example that applies a different height value than the default to a css class selector if the screen is considered small (376px - 464px).
266+
267+
_breakpoints.scss
268+
```
269+
$sm-min: 376px;
270+
$sm-max: 464px;
271+
272+
@mixin sm {
273+
@media (min-width: #{$sm-min}) and (max-width: #{$sm-max}){
274+
@content;
275+
}
276+
}
277+
```
278+
279+
example.scss
280+
```
281+
@import '../lib/styles';
282+
283+
.example {
284+
height: 100px;
285+
@include sm {
286+
height: 50px;
287+
}
288+
}
289+
```
290+
291+
## Icons
292+
### Heroicons
293+
We use the SVG icons library [Heroicons](https://heroicons.com/), where each icon is available in an `outline` or `solid` version.
294+
We import both sets of icons in the file `src-ts/lib/svgs/index.ts`.
295+
```
296+
import * as IconOutline from '@heroicons/react/outline'
297+
import * as IconSolid from '@heroicons/react/solid'
298+
```
299+
300+
Then, to use an icon from either of these sets, you would import the corresponding set into your JSX file and reference the icon of your choice as a component:
301+
302+
e.g.:
303+
```
304+
<IconOutline.InformationCircleIcon width={28} height={28} />
305+
```
306+
307+
### Custom SVGs
308+
Custom SVGs can also be imported and used directly as a React component. Save your SVG in its own file within `src-ts/lib/svgs`, and then import the SVG within `src-ts/lib/svgs/index.ts` as a
309+
component.
310+
```
311+
import { ReactComponent as CustomSVG } from './customSvg.svg'
312+
```
313+
314+
### Styling Icons
315+
316+
You can style an SVG icon by overwritting its properties through CSS (height, width, fill, etc.).
317+
There are also existing mixins located in `src-ts/lib/styles/_icons.scss` with pre-defined widths and heights for various icon sizes.
318+
319+
e.g.:
320+
```
321+
.logo-link {
322+
svg {
323+
width: calc($pad-xxl + $pad-xxxxl);
324+
height: $pad-xl;
325+
fill: none;
326+
327+
path {
328+
fill: $tc-white;
329+
}
330+
}
331+
}
332+
333+
.no-logo-link {
334+
svg {
335+
@include icon-lg;
336+
}
337+
}
338+
```
339+

0 commit comments

Comments
 (0)