Skip to content

Setting up a dev environment

Jump to bottom
Louise Davies edited this page May 22, 2019 · 41 revisions

Required Tools

To develop the DAaaS frontend you will need the following tools:

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

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.

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 development

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/daaas-frontend.git

You then need to install the dependencies with

npm install

When switching branches you may need to run npm 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 npm having mismatching versions and getting stuck and unable to upgrade. This can usually be fixed by deleting the node_modules folder and running npm install freshly (warning: reinstalling all dependencies will take a little while!)

Hosting plugins for development

The parent app needs to know what plugins it has to host itself. There is a serve-plugins.js script that is called as part of npm 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_build_folder_for_plugin",
      "port": 5001
    }
  ]
}

N.B. you only need to add plugins here if you want the parent app to host them during development.

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). 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
  • 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!"}

Starting the site

The site can then be started in development mode using

npm start

Common commands

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