Frontend Web App

The ViRelAy application is built around two core components: a backend REST API and a frontend web app. This section delves into the detailed architecture of the frontend web app.

The frontend is developed using TypeScript , Angular and Clarity , a renowned design system that offers pre-built UI components tailored for Angular applications.

The source code of the frontend can be found in the source/frontend directory. This directory contains the following files and directories:

  • app – Contains main.ts, the primary entrypoint to the Angular application, as well as the app component, the HTML index file, and the route definitions.

  • assets – Contains images and the favicon.

  • components – Contains reusable Angular components such as the embedding viewer.

  • config – Contains the configuration of the web app for different environments (develop and production).

  • pages – Contains Angular components that represent the pages of the web app, such as the project page, which displays a single loaded project.

  • services – Contains services that interact with the backend REST API. There are separate services for each endpoint of the backend: projects, datasets, attributions, color maps, and analyses.

  • styles – Contains the main stylesheets of the web app, which are available to the entire Angular application. The ViRelAy frontend utilizes SCSS, which is a CSS like language frontend for SASS , for its stylesheets.

  • angular.json – Configures the Angular CLI and compiler.

  • package.json – Contains the project dependencies and other metadata.

  • tsconfig.json – Configures the TypeScript compiler.

Development Environment Setup

To start frontend development, it is essential to install Node.js , a prerequisite for Angular. We recommend installing an active LTS or maintenance LTS release of Node.js, which can be easily accomplished through the Node Version Manager (nvm) . Once Node.js is installed, the following command can be used to install the dependencies:

$ npm --prefix source/frontend install

Subsequently, the frontend can be started using the following command. This will start a development server and establish a local development environment that automatically re-compiles and reloads the application upon any changes to source files, while also generating source maps for the compiled JavaScript code for enhanced debugging capabilities.

$ npm --prefix source/frontend run start

To ensure that the frontend properly works, the backend REST API must be started in debug mode using the following command. Debug mode enables log messages to be printed to the console and prevents the frontend from being served through the backend server. This is important for development, as the frontend is being served directly by the Angular CLI.

$ uv run virelay '<project-file>' --debug-mode

Building the Frontend

The frontend application is automatically compiled when the backend REST API project is built. However, for manual compilation, use the following command:

$ npm --prefix source/frontend run build

This command compiles the frontend code in production mode, incorporating optimizations and appending a hash to the file names to prevent cached versions from being served by the server. The compiled frontend output can be found in source/frontend/distribution/browser . If the backend REST API is run without the --debug-mode flag, this is the location from where the frontend is served. Therefore, the frontend must be build before running the backend REST API locally without the --debug-mode flag.

Linting

The frontend web app adheres to a rigorous code style, which is enforced by utilizing tools like ESLint , a JavaScript/TypeScript linter, Stylelint , a CSS/Sass linter, and HTML-Validate , an HTML linter. These checks are integral to identifying potential runtime bugs and ensuring the quality of our codebase. It is essential that contributors regularly run these tools and rectify any warnings that arise. Moreover, it is imperative to verify the absence of warnings before committing changes or creating pull requests. The linting process is integrated into our CI pipeline, which automatically runs upon the creation of a pull request. Any pull request resulting in a failed build will not be accepted.

To keep the configurations for ESLint , Stylelint , and HTML-Validate separate from the frontend project and together with the configurations of the other linters, they are wrapped in their own NPM packages: tests/linters/eslint , tests/linters/stylelint , and tests/linters/html-validate (also, ESLint and StyleLnt dot not support configuration files that are not in the same directory as the NPM package that is being linted). The below commands install the dependencies for these packages. This is required to run the linters locally.

$ npm --prefix tests/linters/eslint install
$ npm --prefix tests/linters/stylelint install
$ npm --prefix tests/linters/html-validate install

The configuration files for each tool are located in the tests/linters directory:

The easiest way to run the linters is through NPM, which can be achieved using the following commands:

$ npm --prefix source/frontend run eslint
$ npm --prefix source/frontend run stylelint
$ npm --prefix source/frontend run html-validate

Note

If you use Visual Studio Code and the HTML-Validate extension , you need to symlink the configuration file to the root of the workspace, as the extension does not support configuration files in sub directories. This can be done by running the following command:

$ ln -s tests/config/.htmlvalidate.js .htmlvalidate.js

The symlink is already ignored in the .gitignore file, so that it is not committed to the repository.