Mercurial > gemma

annotate client/docs/dev-generalconsiderations.md @ 5652:9b3779f649c2 v5.7.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bumped version for release.
author Sascha Wilde <wilde@sha-bang.de>
date Mon, 07 Aug 2023 17:59:18 +0200
parents b372fbe15300
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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