Flexible Interactive Automation frontend

This repository is for the frontend web application side of FIA. It uses Yarn, React, TypeScript, Vite, Material UI, and serves as a plugin for SciGateway. The application allows users to view and manage runs and reductions performed by ISIS instruments.

Starting development

Downloading the code

To get started developing for the frontend, first you will need to have Node.js and Yarn installed and set-up on your machine. When following the install wizards just keep to default settings. You will then want to clone the SciGateway repository. From now on stick to SciGateway's release/v3.0.0 branch (worth noting that develop is the repository's default branch instead of "main" or "master").

With that done, you can now clone the FIA frontend repository.

Setting up FIA as a plugin

The frontend works by building the project and then running it through SciGateway as a plugin. You will want to create a settings.json file in SciGateway's public folder. Do this by simply duplicating settings.example.json and renaming it. A few adjustments will need to be made, like adding FIA as a plugin, setting "homepageUrl" to "/fia", and pointing the "authUrl" to "https://dev.reduce.isis.cclrc.ac.uk/auth". The "auth-provider" can be set to null or "jwt". Aside from that, keep everything else as is:

// settings.json
"plugins": [
  {
    "name": "fia",
    "src": "http://localhost:5001/main.js",
    "enable": true,
    "location": "main"
  }

  "auth-provider": null,
  "authUrl": "https://dev.reduce.isis.cclrc.ac.uk/auth",
  "homepageUrl": "/fia"
]

A dev-plugin-settings.json file is also needed in SciGateway's micro-frontend-tools folder. Like before, simply duplicate dev-plugin-settings.example.json, rename it, and add the path to the FIA frontend build folder:

// dev-plugin-settings.json
"plugins": [
  {
    "type": "static",
    "location": "C:\\[path]\\[to]\\frontend\\build", // Replace [path] and [to] with the actual path
    "port": 5001
  }
]

Specifying environment variables

Unless you have a working API and data viewer set up locally, point the frontend at the staging services (requires site VPN). Vite uses VITE_* environment variables. See .env for examples:

• VITE_FIA_REST_API_URL
• VITE_FIA_DATA_VIEWER_URL
• VITE_PLUGIN_URL (used for certain asset URLs)
• VITE_DEV_MODE (optional)

If you want to run the experiment viewer, you must have the plotting service running locally as remote server restricts access from the outside. To control where the plotting service is running, set VITE_FIA_PLOTTING_API_URL in your .env file.

Running the frontend for the first time

Assuming all the previous steps have been completed, you can now use these commands in the terminal to get the web application running.

yarn install

Installs the necessary dependencies for the project. Run this after adding new dependencies or switching to branches with a modified package.json.

yarn build

Builds the app with Vite into build/ for use as a SciGateway plugin. Do this whenever the frontend changes; build/ is not tracked by Git and SciGateway serves this folder.

Notes:

• The default build expects React and ReactDOM to be provided by the host (externals). If your host does not provide them, use yarn build:standalone to bundle React into build/main.js.
• On Windows, SciGateway may lock files in build/ while serving them. Stop SciGateway before rebuilding to avoid EPERM errors.

yarn start

Runs the Vite dev server on http://localhost:3000.

• For quick standalone development (no SciGateway), the web app will be hosted at http://localhost:3000 by default.
• For testing as a plugin for SciGateway, build with yarn build and start SciGateway. The plugin will be available at the route configured in SciGateway.

Other useful dev commands:

• yarn preview: Serves the built build/ output for local checks.
• yarn serve:build: Builds and previews on port 5001.

Container files

Certain features of the frontend such as the help page are handled by files in SciGateway which are overwritten during production to display the correct information to users. Files for this purpose are stored in the container folder. Any changes made locally to this folder won't be visible when running the web application using yarn start. So to test changes, you either need to modify SciGateway's files or create a container image. To do this we recommend installing and using Docker.

To build the frontend:

docker build . -t ghcr.io/fiaisis/frontend -f ./frontend.dockerfile

To build SciGateway (NOTE: the working directory needs to be in the container folder for this):

docker build . -t ghcr.io/fiaisis/scigateway -f ./scigateway.dockerfile

To run the frontend container:

docker run --rm -it -p 8080:80 ghcr.io/fiaisis/frontend

To run the SciGateway container (NOTE: without the frontend running on the same local network this will not display the plugin):

docker run --rm -it -p 8080:80 ghcr.io/fiaisis/scigateway

To access the websites made by the above containers navigate to http://localhost:8080.

BEWARE: this can give false positives. Do not push changes to SciGateway as we do not develop in that repo.

Package issues

When adding new dependencies to package.json or switching between branches with different dependencies, run yarn install to update the node_modules folder.

Occasionally there are issues with package conflicts that require node_modules and yarn.lock to be deleted and the cache cleared. You can do this with the following command:

rm -rf node_modules && yarn cache clean && rm -f yarn.lock && yarn install

Writing browser tests

The FIA frontend uses Cypress for end-to-end and component testing. These tests run in a workflow whenever a commit is pushed or a pull request is merged. Tests can also be run locally.

For writing your own tests, follow the guide here. Alternatively, replicate the methods used in pre-existing .cy.tsx files, like the homepage.

Additional scripts

Here are a few other scripts to be aware of:

yarn cypress open

Opens the Cypress Test Runner. This provides a graphical display for running end-to-end and component tests within a browser.

yarn cypress run

Runs Cypress tests headlessly in the terminal. This is useful for running tests in a CI/CD pipeline (currently there are no e2e spec files so shouldn't do anything).

yarn run-frontend

A helper script which builds the frontend and then navigates to the SciGateway folder (assuming it's in an adjacent directory) and runs yarn start there.

Learn more

Read more:

• TypeScript documentation
• React documentation
• Yarn documentation
• Vite documentation
• Material UI documentation
• Cypress documentation
• Docker documentation