Skip to content

Setting up a dev environment

Jump to bottom
Louise Davies edited this page Oct 12, 2023 · 41 revisions

Required Tools

To develop the Scigateway you will need the following tools:

  • Node.js (https://nodejs.org/en/) - (LTS version at the time of writing is 16.17.0)
  • NPM (comes with the node.js installation)
  • An IDE for developing with JavaScript (VS Code is a good cross-platform suggestion)
  • Yarn

Installation instructions are available on the sites for each tool and depend on your operating system, e.g. node can be installed as an msi on a windows machine

Note: if installing Node.js on Linux machines please read https://nodejs.org/en/download/package-manager/ as these detail how to ensure you are able to get the most recent version of Node.js on your machine, rather than an old version in the default package.

Helpful tools

  • React Dev Tools extension: Chrome Firefox
  • Redux Dev Tools extension: http://extension.remotedev.io/
  • Useful VSCode extensions:
    • JavaScript development:
      • ESLint - displays eslint errors in the editor
      • npm Intellisense - autocompletes npm import statements
      • npm - validates that dependencies are installed and adds NPM commands to command pallete
      • Prettier - can format files using Prettier - I have it set to format on save ;)
    • Git:
      • GitLens - enhances VSCode git support
    • General:
      • Code Coverage - highlights uncovered lines of code in the editor
  • Useful Atom extensions:
    • General:
      • highlight-selected - highlights the current selected word across the rest of the page
      • file-icons - adds more file icons to make the file tree view easier to use
      • atom-ide-ui - autocomplete, goto definition, hover-to-reveal, and more...
      • lcov-info - highlights uncovered lines of code in the editor
    • React development:
      • ide-typescript - extra TypeScript support for atom-ide-ui including errors and warnings
      • prettier-atom - can format files using Prettier
      • react - React support for Atom (e.g. syntax highlighting and auto-indentation)
      • language-typescript-react - there are some issues with the existing grammar so you may or may not need this

Feel free to add any other helpful tools to this list :)

New developer tutorials

Here's a list of useful tutorials to help new developers learn the technologies required:

Feel free to add any other learning resources you find useful to this section.

Starting parent app development

Setting up parent app

First of all, you will need to clone the code in this repository either using a Git client (e.g. GitKraken) or on the command line

git clone https://github.com/ral-facilities/scigateway.git

You then need to install the dependencies with

yarn install

When switching branches you may need to run yarn install if the branch you are on has installed extra dependencies

If you get errors about dependencies not being met, especially after switching branches, then this may be due to yarn having mismatching versions and getting stuck and unable to upgrade. This can usually be fixed by deleting the node_modules folder and running yarn install freshly (warning: reinstalling all dependencies will take a little while!)

Parent app settings

The parent app also needs a settings.json file in the public folder, this tells the app about all the plugins to load (whether hosted locally or not).

You can use settings.example.json in the public folder or the minimal example below to create a settings.json which can be placed in the public folder to get you started.

{
   "plugins": [
     {
      "name": "demo_plugin",
      "src": "http://localhost:5001/main.js",
      "enable": false,
      "location": "main"
     }
   ],
   "help-tour-steps": [],
   "ui-strings": "/res/default.json",
   "auth-provider": "jwt",
}

If you want to use your own settings file then use settings.example.json as an example - the important part is to make sure the plugin section points to each of the plugins with a few restrictions:

  • the name must be the name the plugin has been built with (i.e. what was the value of webpackConfig.output.library). See an example here.
  • the src is either a relative path from the public folder (e.g. /plugins/plugin1) or more likely a URL (e.g. http://localhost:5002/main.js). If using the micro-frontend-tools above then each URL will be localhost on the port specified in the settings for the tool.
  • you can independently enable/disable plugins using the enable boolean
  • location currently has to be main but does nothing.

There are also other sections:

  • features: turn specific features of the site on or off
  • ui-strings: where to find file that details the strings the UI will use for text - see /public/res/default.json for the defaults
  • auth-provider: what authentication provider to use
    • jwt: run your own auth server which accepts "username" and "password" as valid credentials
    • github: use github account to sign in via redirect
    • icat: to use a server like scigateway-auth which offers multiple different ICAT authenticators
  • help-tour-steps: an array of objects with a CSS selector as the target and the text to display in the tooltip as the content e.g. {target: "#my-tour-step", content: "This is my tour step!"}
  • ga-tracking-id: The google analytics tracking ID to use - see the Analytics page for info on how to find this

Starting the site

The site can then be started in development mode using

yarn start

Starting plugin development

Setting up demo_plugin

In order to get any actual functionality, the parent app needs to load plugins. There is an example plugin called demo_plugin which is useful to install so you can see the plugin loading process working and know the development steps when developing a plugin.

Similar to the parent app, to begin you'll need to clone the git repository.

git clone https://github.com/ral-facilities/scigateway-demo-plugin.git

You then need to install the dependencies with

yarn install

Building the demo plugin

There are two ways to build plugins. For development, it is useful for the plugin to stand alone as it's own application and to be able to develop without the parent app. This is what is done when calling

yarn start

However, this doesn't build the plugin in such a way that the parent application can run it. To do that, you must run

yarn build

To learn more about what this is doing, read Creating a new plugin app

Serving the plugin

There are two ways to host the plugin so that the parent app can load it's code. You can run

yarn serve:build

which builds the plugin and serves it on port 5001.

Alternatively, you can tell the parent application where your plugin build folder is located and it will serve it automatically for you. There is a serve-plugins.js script that is called as part of the parent app's yarn start but it needs a config file to know what plugins to host. Use micro-frontend-tools/dev-plugin-settings.example.json as an example but it could also be a blank array for the plugins field.

As an example dev-plugin-settings.json:

{
  "plugins": [
    {
      "type": "static",
      "location": "/path/to/daaas_frontend_demo_plugin/build",
      "port": 5001
    }
  ]
}

IMPORTANT Either method you choose, you will need to update the parent app's public/settings.json file to tell it where to find the plugin. If you used the minimal example settings.json file - you merely need to switch enable from false to true.

Common commands

Here is a list of common commands used in development and a short description of what they do

  • yarn start - start the development server that does hot reloading
  • yarn build - build the final bundled javascript
  • yarn test - run the tests and calculate the coverage
  • yarn test:watch - run the tests and watch for changes in order to run the tests again
  • yarn lint:js - lint (and fix as much as possible) the typescript/javascript code
  • yarn e2e - run the end-to-end tests in a headless mode (useful for CI systems)
  • yarn e2e:interactive - run the end-to-end tests interactively (useful for debugging e2e tests)
  • yarn storybook - starts a storybook server to display component stories

More commands can be found in package.json - specifically in the scripts section

Clone this wiki locally