Frontend development setup

[]

Warning Backend development and frontend development are mutually exclusive and should not be done at the same time.

Prerequisites

Developer machine requirements

On your local machine, you just need a standard JavaScript/TypesScript development environment:

Node 16 and corresponding npm
Native compilation toolchain, required by some npm libraries. On OS X, this is automatically part of the Xcode development environment and/or standard OS.
- C and C++ compiler
- GNU Make
- python (version 3)

Running backend

The frontend always requires a proper backend, with both backend services - HCMS and HCMS Client middleware - available and correctly accessible. How to set them up, is describe in the local installation chapter. For the purposes of the frontend development, you can have your backend running locally, on a remote server, or in a cloud.

The usual way to develop frontend is to use an already existing server setup, connecting to both backend systems remotely with a specially configured browser, with all security features disabled. Unfortunately, this is not allowed by default by any modern browsers, and the backend needs to be configured to override those security settings.

The next section provides a detailed information on how to get a "local" installation running non-locally.

Important: Lowering security level is a decision to be made by system administrators and project managers. If your role in the project is different from that, please consult with them and obtain all necessary data.

Development setup options

Complete local development setup

The recommended solution is to run the standalone Docker Compose setup with the development flag enabled. It takes care of all necessary issues.

This setup can be run on a local machine via Docker Desktop, or on some internal development server that is not exposed to the public, e.g. firewalled.

Remote server setup

The system administrator can perform a complete local installation on a remote (at best, a Linux) server and then provide all frontend developers with:

HTTP proxy configuration (host and port)
domain name accessible via that proxy (https://<domain>)

Cloud environment setup

As an alternative, some cloud environment can be reconfigured to bypass the security requirements, specifically, by setting special CORS headers and SameSite=None. But the backend still must be available via https; there is absolutely no way to make this work over plain http.

Note that these instructions are for the administrator, not for the developer.

In the HCMS configuration, set authorisation cookie to use sameSite="None" flag:
XML
```
   <cookie name="access_token" same-site="None"/>
```
In the HCMS configuration, enable CORS for all sites:
XML
```
     <api allowedOrigins="*">
```
or just the localhost (please note that all possible port numbers in use must be set)
XML
```
     <api allowedOrigins="http://localhost:3390/,http://localhost:3000/">
```
Run the hcms-client docker container with the environment variable DISABLE_BROWSER_SECURITY=true. This actually does the same as the previous steps, but in the middleware.

Warning: Make sure that this environment is accessible only to developers and not from any external network (ie it's firewalled).

Domain name

Independently of the selected development setup, you need to know the domain name to use it on later steps.

React development requires just one single URL, usually in the form of https://<domain>/data/config.json. This domain is either:

the domain chosen in the local standalone configuration
- Please remember that in this case, it will work only in a browser with the http proxy configured!
the correct domain of the development environment

Starting the development

Those are the last steps before the actual development.

Configuration

You need to create some configuration.

cd frontend-app
Create web/data/config.json.
- Use <code>config.local.json</code> as a template
- Set backendConfigUrl to the full URL of remote config.json, i.e., to https://<domain>/data/config.json obtained on the previous step
- Add all the modules you want to work on

Example content of config.json:

JSON

{
  "backendConfigUrl": "https://portal-name.dev.portal.censhare.io/data/config.json",
  "forceSetCookieViaQueryParam": false,
  "modules": [
    {
      "id": "media",
      "name": "Media",
      "src": "http://localhost:3392/module.js",
      "icon": "photo_library",
      "modules": [
        {
          "icon": "filter_none",
          "id": "collections",
          "library": "media",
          "name": "Collections"
        },
        {
          "icon": "library_add",
          "id": "uploads",
          "library": "media",
          "name": "My uploads"
        }
      ]
    },
    {
      "id": "person",
      "name": "People",
      "src": "http://localhost:3391/module.js",
      "icon": "person"
    },
        {
      "group": {"id": "settings", "name": "Settings", "icon": "settings"},
      "id": "auth",
      "name": "Authentication",
      "src": "http://localhost:3397/module.js",
      "icon": "lock"
    },
    {
      "group": {"id": "settings", "name": "Settings", "icon": "settings"},
      "id": "theming",
      "name": "Theming",
      "src": "http://localhost:3394/module.js",
      "icon": "format_paint"
    }
  ]
}

Install and start the core module

You need to run the out-of-the-box core module, the backbone of the frontend, to see your own changes later.

Note We strongly recommend disabling the compilation feature of the IDE since the IDE-based incremental compilation can lead to a few issues. You‘d also have to make sure that the IDE correctly uses the tsconfig.json configuration - in particular, the output directories must be the same. So, instead of setting up redundant developer project features, it is much better to disable IDE support.

cd frontend-app
npm ci or npm install to install the dependencies and devDependencies.
npm run dev to start the core module
- or npm run dev-all-modules to force visibility of all modules regardless of user/server roles configuration.
Open the http://localhost:3390 URL in a browser
- Make sure that the browser is the correct development instance, i.e. with an http proxy from the and maybe also with disabled web security.

Note that usually at least one of the other modules needs to be run.

Notes on CORS

To avoid CORS issue you can turn on Google Chrome in special mode which means that security is disabled. Both parameters are required.
SHELL
```
"[PATH_TO_CHROME]\chrome.exe" --disable-web-security --user-data-dir=~/chromeTemp
```
Regarding CORS requests and reverse proxy, there have been isolated cases in the past where the HTTP authentication header was lost. To adress this issue, you should set the forceSetCookieViaQueryParam to true in the web/data/config.json. Please note that because of security concerns this approach is only intended for use in development environments and does not work in production.