|
1 | | -# Webclient |
2 | | - |
3 | | -This folder contains the JavaScript based webclient for NavigaTUM. |
4 | | - |
5 | | -## Getting started |
6 | | - |
7 | | -### Prerequisites |
8 | | - |
9 | | -For getting started, there are some system dependencys which you will need. |
10 | | -Please follow the [system dependencys docs](/resources/documentation/Dependencys.md) before trying to run this part of our project. |
11 | | - |
12 | | -### Recommended IDE Setup |
13 | | - |
14 | | -[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin). |
15 | | -Most modern IDEs (like PyCharm) should work as well and have a Plugin. |
16 | | - |
17 | | -## Dependencies |
18 | | - |
19 | | -### Prerequisites |
20 | | - |
21 | | -For getting started, there are some system dependencys which you will need. |
22 | | -Please follow the [system dependencys docs](/resources/documentation/Dependencys.md) before trying to run this part of our project. |
23 | | - |
24 | | -### Installing Dependency's |
25 | | - |
26 | | -```bash |
27 | | -pnpm install |
28 | | -``` |
29 | | - |
30 | | -## Run |
31 | | - |
32 | | -Ensure that _NavigaTUM-server_ is running in the background. |
33 | | -By default, the webclient will connect to the server on `https://nav.tum.de`. |
34 | | -If you want to connect to a local version instead, change the environemnt variable `NUXT_PUBLIC_{API,CDN,FEEDBACK,MAPS}_URL` to the appropriate value. |
35 | | - |
36 | | -To get a local server running, please: |
37 | | - |
38 | | -- either via following the [guide to local development](../server/README.md), or |
39 | | -- via [docker](https://docs.docker.com/) |
40 | | - _docker isolates the network, but we want these two containers to communicate to each other without being as brittle as IPs._ |
41 | | - _Naming the `navigatum-mieli-search` container `search` makes us able to connect to it via <`http://search:7700`> from the server_ |
42 | | - |
43 | | - ```bash |
44 | | - docker network create navigatum-net |
45 | | - docker run -it --rm -p 7700:7700 --name search --network navigatum-net ghcr.io/tum-dev/navigatum-mieli-search:main |
46 | | - docker run -it --rm -p 8080:8080 --network navigatum-net -e MIELI_SEARCH_ADDR=search ghcr.io/tum-dev/navigatum-server:main /bin/navigatum-main-api |
47 | | - ``` |
48 | | - |
49 | | -```sh |
50 | | -pnpm run dev |
51 | | -``` |
52 | | - |
53 | | -### Type-Check, Compile and Minify for Production |
54 | | - |
55 | | -```sh |
56 | | -pnpm run build |
57 | | -``` |
58 | | - |
59 | | -### Linting with [ESLint](https://eslint.org/) and formatting via prettier |
60 | | - |
61 | | -```sh |
62 | | -pnpm run lint |
63 | | -pnpm run format |
64 | | -``` |
65 | | - |
66 | | -### Update the API's type definitions |
67 | | - |
68 | | -From the folder of this README, run: |
69 | | - |
70 | | -```sh |
71 | | -pnpm run type-refresh |
72 | | -``` |
73 | | - |
74 | | -## Architecture |
75 | | - |
76 | | -The NavigaTUM webclient is made as a nuxt3 server side rendered application based on [Vue.js](https://vuejs.org/) and [Vue Router](https://router.vuejs.org/). |
77 | | -Our CSS framework is [Tailwind](https://tailwindcss.com/). |
78 | | - |
79 | | -### Directory structure (only the important parts) |
80 | | - |
81 | | -```plain |
82 | | -webclient |
83 | | -├── public/ # 🠔 Static assets such as icons, which cannot get inlined |
84 | | -├── api_types/ # 🠔 code generated via openapi.yaml for typechecking reasons |
85 | | -├── content/ # 🠔 Static pages written in markdown. Served at `/about/<filename>`. |
86 | | -├── assets/ # 🠔 Static assets such as icons |
87 | | -│ ├── main.scss # 🠔 Sass CSS code for all non-view parts |
88 | | -│ └── logos # 🠔 The Logos used by the app |
89 | | -├── components/ # 🠔 Vue components, which are used in views. |
90 | | -├── pages/ # 🠔 The pages are parts of App.vue, which are loaded based their file names. |
91 | | -├── nuxt.config.ts # 🠔 core configuration of nuxt |
92 | | -└── package.json # 🠔 Node package definition and dependencies |
93 | | -``` |
94 | | - |
95 | | -Note that new views are automatically included in the build, but they are not routed. |
96 | | -To add a new view, you need to add a new route in `router.ts`. |
97 | | - |
98 | | -## Testing |
99 | | - |
100 | | -> [!NOTE] |
101 | | -> cypress is currently temporarily disabled to help in the nuxt transition |
102 | | -
|
103 | | -For this part of the project, the tests consist mainly of hot-path e2e tests and tests of critical components. |
104 | | -PRs improving the coverage are very likely to be accepted. |
105 | | -The reason behind these tests is that they fundamentally increase the future productivity by allowing faster review cycles. |
106 | | - |
107 | | -### Continuous Integration |
108 | | - |
109 | | -Every push and pull request triggers a build that runs linting issues (cypress is currently temporarily disabled to help in the nuxt transition). |
110 | | -This helps us catch any regressions or issues early in the development process. |
111 | | - |
112 | | -### Reporting Issues |
113 | | - |
114 | | -If you encounter any problems while running the Cypress tests or have suggestions for improving the testing framework, please open an issue/pull request on this repository. |
115 | | -We appreciate your feedback and contributions. |
| 1 | +# Webclient |
| 2 | + |
| 3 | +This folder contains the JavaScript based webclient for NavigaTUM. |
| 4 | + |
| 5 | +## Getting started |
| 6 | + |
| 7 | +### Prerequisites |
| 8 | + |
| 9 | +For getting started, there are some system dependencys which you will need. |
| 10 | +Please follow the [system dependencys docs](/resources/documentation/Dependencys.md) before trying to run this part of our project. |
| 11 | + |
| 12 | +### Recommended IDE Setup |
| 13 | + |
| 14 | +[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin). |
| 15 | +Most modern IDEs (like PyCharm) should work as well and have a Plugin. |
| 16 | + |
| 17 | +## Dependencies |
| 18 | + |
| 19 | +### Prerequisites |
| 20 | + |
| 21 | +For getting started, there are some system dependencys which you will need. |
| 22 | +Please follow the [system dependencys docs](/resources/documentation/Dependencys.md) before trying to run this part of our project. |
| 23 | + |
| 24 | +### Installing Dependency's |
| 25 | + |
| 26 | +```bash |
| 27 | +pnpm install |
| 28 | +``` |
| 29 | + |
| 30 | +## Run |
| 31 | + |
| 32 | +Ensure that _NavigaTUM-server_ is running in the background. |
| 33 | +By default, the webclient will connect to the server on `https://nav.tum.de`. |
| 34 | +If you want to connect to a local version instead, change the environemnt variable `NUXT_PUBLIC_{API,CDN,FEEDBACK,MAPS}_URL` to the appropriate value. |
| 35 | + |
| 36 | +To get a local server running, please: |
| 37 | + |
| 38 | +- either via following the [guide to local development](../server/README.md), or |
| 39 | +- via [docker](https://docs.docker.com/) |
| 40 | + _docker isolates the network, but we want these two containers to communicate to each other without being as brittle as IPs._ |
| 41 | + _Naming the `navigatum-mieli-search` container `search` makes us able to connect to it via <`http://search:7700`> from the server_ |
| 42 | + |
| 43 | + ```bash |
| 44 | + docker network create navigatum-net |
| 45 | + docker run -it --rm -p 7700:7700 --name search --network navigatum-net ghcr.io/tum-dev/navigatum-mieli-search:main |
| 46 | + docker run -it --rm -p 8080:8080 --network navigatum-net -e MIELI_SEARCH_ADDR=search ghcr.io/tum-dev/navigatum-server:main /bin/navigatum-main-api |
| 47 | + ``` |
| 48 | + |
| 49 | +```sh |
| 50 | +pnpm run dev |
| 51 | +``` |
| 52 | + |
| 53 | +### Type-Check, Compile and Minify for Production |
| 54 | + |
| 55 | +```sh |
| 56 | +pnpm run build |
| 57 | +``` |
| 58 | + |
| 59 | +### Linting with [ESLint](https://eslint.org/) and formatting via prettier |
| 60 | + |
| 61 | +```sh |
| 62 | +pnpm run lint |
| 63 | +pnpm run format |
| 64 | +``` |
| 65 | + |
| 66 | +### Update the API's type definitions |
| 67 | + |
| 68 | +From the folder of this README, run: |
| 69 | + |
| 70 | +```sh |
| 71 | +pnpm run type-refresh |
| 72 | +``` |
| 73 | + |
| 74 | +## Architecture |
| 75 | + |
| 76 | +The NavigaTUM webclient is made as a nuxt3 server side rendered application based on [Vue.js](https://vuejs.org/) and [Vue Router](https://router.vuejs.org/). |
| 77 | +Our CSS framework is [Tailwind](https://tailwindcss.com/). |
| 78 | + |
| 79 | +### Directory structure (only the important parts) |
| 80 | + |
| 81 | +```plain |
| 82 | +webclient |
| 83 | +├── public/ # 🠔 Static assets such as icons, which cannot get inlined |
| 84 | +├── api_types/ # 🠔 code generated via openapi.yaml for typechecking reasons |
| 85 | +├── content/ # 🠔 Static pages written in markdown. Served at `/about/<filename>`. |
| 86 | +├── assets/ # 🠔 Static assets such as icons |
| 87 | +│ ├── main.scss # 🠔 Sass CSS code for all non-view parts |
| 88 | +│ └── logos # 🠔 The Logos used by the app |
| 89 | +├── components/ # 🠔 Vue components, which are used in views. |
| 90 | +├── pages/ # 🠔 The pages are parts of App.vue, which are loaded based their file names. |
| 91 | +├── nuxt.config.ts # 🠔 core configuration of nuxt |
| 92 | +└── package.json # 🠔 Node package definition and dependencies |
| 93 | +``` |
| 94 | + |
| 95 | +Note that new views are automatically included in the build, but they are not routed. |
| 96 | +To add a new view, you need to add a new route in `router.ts`. |
| 97 | + |
| 98 | +## Testing |
| 99 | + |
| 100 | +> [!NOTE] |
| 101 | +> cypress is currently temporarily disabled to help in the nuxt transition |
| 102 | +
|
| 103 | +For this part of the project, the tests consist mainly of hot-path e2e tests and tests of critical components. |
| 104 | +PRs improving the coverage are very likely to be accepted. |
| 105 | +The reason behind these tests is that they fundamentally increase the future productivity by allowing faster review cycles. |
| 106 | + |
| 107 | +### Continuous Integration |
| 108 | + |
| 109 | +Every push and pull request triggers a build that runs linting issues (cypress is currently temporarily disabled to help in the nuxt transition). |
| 110 | +This helps us catch any regressions or issues early in the development process. |
| 111 | + |
| 112 | +### Reporting Issues |
| 113 | + |
| 114 | +If you encounter any problems while running the Cypress tests or have suggestions for improving the testing framework, please open an issue/pull request on this repository. |
| 115 | +We appreciate your feedback and contributions. |
0 commit comments