Mercurial > gemma
annotate client/docs/dev-generalconsiderations.md @ 4644:486495590483
Merged stree-experiment into default to benefit from diff improvements.
author | Sascha L. Teichmann <sascha.teichmann@intevation.de> |
---|---|
date | Sat, 12 Oct 2019 15:17:51 +0200 |
parents | b372fbe15300 |
children |
rev | line source |
---|---|
482
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
1 # General considerations |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
2 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
3 ## We chose [vuejs](https://vuejs.org/) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
4 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
5 Vue is a modern framework for webdevelopment. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
6 It offers a very homogenous ecosystem (vuejs, vuecli, vue-router vuex) combined with up to date fontend rendering techniques like virtual DOM. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
7 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
8 ## We chose [vue cli](https://cli.vuejs.org/) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
9 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
10 Vue cli allows a good jumpstart for a vuejs project. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
11 There is no manual boilerplate to write. Everything is in place and already wired. The skeleton is easy extendable and in contrast to |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
12 other frameworks (i.e. create-react-app) there is no "eject" for further customization necessary. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
13 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
14 Configuration: |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
15 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
16 - Babel |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
17 - Router |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
18 - Vuex |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
19 - CSSPreprocessor |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
20 - Linter+Unit |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
21 - Testing+E2E |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
22 - Testing |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
23 - No Typescript (No advantages) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
24 - No PWA (IE11 compatibility makes more modern approaches unavailable) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
25 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
26 - SASS as CSS Preprocessor (widely used, allows programmatic CSS, familarity) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
27 - Eslint + Prettier (Rationale below) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
28 - Lint on Save |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
29 - Jest as Unittesting framework (zeroconf, ease of use) [productpage](https://jestjs.io/ |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
30 - Nightwatch (Seleniumbased, familarity with selenium, Chromedriver ootB) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
31 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
32 Everything in dedicated config files |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
33 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
34 ## We chose [vuex](https://vuex.vuejs.org/guide/) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
35 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
36 Vuex is the store component of vuejs. For medium to complex applications it is reasonable to centralize state globally, to make every possible interaction with state transparent. Interactions with state become traceable in contrast to chains built with components and properties. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
37 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
38 Perhaps it is resonable to configure [strict mode](https://vuex.vuejs.org/api/#strict) in the future (for development). State changes should only be allowed through `actions` and `mutations`. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
39 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
40 Besides traceability vuex allows to dumb down components. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
41 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
42 ## We chose [prettier](https://prettier.io/) in combination with [eslint](https://eslint.org/) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
43 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
44 To enforce tight styling guidelines (e.g. avoidance of problems with [semicolons](https://eslint.org/docs/rules/no-unexpected-multiline)) and strict formatting rules, prettier was chosen. Prettier as a plugin is widey supported: |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
45 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
46 - [vim](https://github.com/prettier/vim-prettier) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
47 - [emacs](https://github.com/prettier/prettier-emacs) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
48 - [VSCode](https://github.com/prettier/prettier-vscode) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
49 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
50 On top, there is [pretty quick](https://www.npmjs.com/package/pretty-quick) a tool, which allows autmatically solving linting issues for you. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
51 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
52 Overall prettier makes styling issues a non-issue: You get achieve styled code as a result. Code which is automatically formatted is easier to read for humans (it is in every project the same guideline) and easier to read for machines (which offer help like `pretty-quick`). |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
53 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
54 Similar philosophy as behind [gofmt](https://golang.org/cmd/gofmt/) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
55 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
56 ## We chose [env](https://github.com/motdotla/dotenv) as configurtion file format |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
57 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
58 It is good practice to store configuration in the environment (see [12 factor app](https://12factor.net/config)). |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
59 From this idea evolved the practice to use `.env` files for configuring the environment. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
60 `.env` is a standard widely supported, e.g. |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
61 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
62 - [go](https://github.com/joho/godotenv) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
63 - [Node](https://www.npmjs.com/package/dotenv) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
64 - [Webpack](https://www.npmjs.com/package/dotenv-webpack) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
65 |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
66 Last but not least: `.env` is the format, which is used by [vue-cli](https://cli.vuejs.org/guide/mode-and-env.html) |
3e5ed9f40095
docs: Rationale for clientside framework decisions
Thomas Junk <thomas.junk@intevation.de>
parents:
168
diff
changeset
|
67 |