Skip to content

Latest commit

 

History

History
115 lines (79 loc) · 4.38 KB

README.md

File metadata and controls

115 lines (79 loc) · 4.38 KB
Raw

Webclient

This folder contains the JavaScript based webclient for NavigaTUM.

Getting started

Prerequisites

For getting started, there are some system dependencys which you will need. Please follow the system dependencys docs before trying to run this part of our project.

Recommended IDE Setup

VSCode + Volar (and disable Vetur) + TypeScript Vue Plugin (Volar). Most modern IDEs (like PyCharm) should work as well and have a Plugin.

Dependencies

Prerequisites

For getting started, there are some system dependencys which you will need. Please follow the system dependencys docs before trying to run this part of our project.

Installing Dependency's

pnpm install

Run

Ensure that NavigaTUM-server is running in the background. By default, the webclient will connect to the server on https://nav.tum.de.
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.

To get a local server running, please:

  • either via following the guide to local development, or

  • via docker
    docker isolates the network, but we want these two containers to communicate to each other without being as brittle as IPs.
    Naming the navigatum-mieli-search container search makes us able to connect to it via <http://search:7700> from the server

    docker network create navigatum-net
docker run -it --rm -p 7700:7700 --name search --network navigatum-net ghcr.io/tum-dev/navigatum-mieli-search:main
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
pnpm run dev

Type-Check, Compile and Minify for Production

pnpm run build

Linting with ESLint and formatting via prettier

pnpm run lint
pnpm run format

Update the API's type definitions

From the folder of this README, run:

pnpm run type-refresh

Architecture

The NavigaTUM webclient is made as a nuxt3 server side rendered application based on Vue.js and Vue Router. Our CSS framework is Tailwind.

Directory structure (only the important parts)

webclient
├── public/        # 🠔 Static assets such as icons, which cannot get inlined
├── api_types/     # 🠔 code generated via openapi.yaml for typechecking reasons
├── content/       # 🠔 Static pages written in markdown. Served at `/about/<filename>`.
├── assets/        # 🠔 Static assets such as icons
│   ├── main.scss  # 🠔 Sass CSS code for all non-view parts
│   └── logos      # 🠔 The Logos used by the app
├── components/    # 🠔 Vue components, which are used in views.
├── pages/         # 🠔 The pages are parts of App.vue, which are loaded based their file names.
├── nuxt.config.ts # 🠔 core configuration of nuxt
└── package.json   # 🠔 Node package definition and dependencies

Note that new views are automatically included in the build, but they are not routed.
To add a new view, you need to add a new route in router.ts.

Testing

Note

cypress is currently temporarily disabled to help in the nuxt transition

For this part of the project, the tests consist mainly of hot-path e2e tests and tests of critical components. PRs improving the coverage are very likely to be accepted. The reason behind these tests is that they fundamentally increase the future productivity by allowing faster review cycles.

Continuous Integration

Every push and pull request triggers a build that runs linting issues (cypress is currently temporarily disabled to help in the nuxt transition). This helps us catch any regressions or issues early in the development process.

Reporting Issues

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. We appreciate your feedback and contributions.