Skip to content

Development Environment

Jump to bottom
Will Rogers edited this page Feb 25, 2021 · 24 revisions

This page describes the development environment being used at Diamond Light Source to work on web projects. Depending on your computer's settings, some details may need to be changed.

NPM and Node

Node Package Manager (npm) is a tool for installing javascript libraries, for use both in the browser or within Node. Node is the most popular javascript server-side runtime environments and is entirely free. cs-web-proto uses node to serve a web page.

Manual installation

Download the right version for your system here: https://nodejs.org/en/download/

It may be necessary to extract the binary into /scratch or a similar local folder you have access rights to. If so, you will also have to manually add the node binaries to your path, or add an alias to full path for each binary you want to use.

If installed in /scratch, you can add commands to your $PATH like so:

PATH="$PATH:/scratch/node-v10.16.1-linux-x64/bin/"

You will probably want to add this to your bashrc file.

Installing on Debian-based systems

apt install npm

This brings node in as a dependency.

Using npm

You can use this to set up cs-web-proto like so: cloning the cs-web-proto repository associated with this page, install the packages it requires and start the webserver:

git clone https://github.com/dls-controls/cs-web-proto.git
cd cs-web-proto
npm install
npm start

To add a new dependency, use npm install as well:

npm install package-name

Testing

To run the tests in 'watch' mode, where any changes trigger a test run:

npm test

To run all tests once:

npm test -- --watchAll=false

To run all tests once with a coverage report:

npm test -- --watchAll=false --coverage

Debugging in Firefox

Here are some extensions you may wish to add to Firefox to make it easier to debug during development:

VSCode setup

VSCode is a free IDE developed by Microsoft which has become very popular for web development. It also has a number of useful extensions which make life a bit easier and will be discussed shortly.

Installation

From the downloads page you can download the VSCode binary as a .tar.gz file and extract this to /scratch or a similar local directory you have installation rights over.

You should then be able to start VSCode with:

/scratch/VSCode-linux-x64/bin/code

Extensions

If you have had to put VSCode in a /scratch type directory, you will also need to take some steps to install your extensions properly.

Go to the VSCode directory and create a folder called data:

cd /scratch/VSCode-linux-x64
mkdir data

You should now be able to use the extensions tab (accessible via Ctrl+Shift+X) in VSCode to install extensions.

Here are the extensions we have installed in our VSCode installations:

  • Prettier - formats your Javascript in a standard way, improving readability and avoiding unnecessarily differences between files. This is used fairly widely and useful for collaboration
    • We also found it useful to automatically perform formatting on save, set this in the preferences by going to File > Preferences > Settings and search for editor format then tick the box entitled editor: Format On Save
  • Jest - testing framework which is used in many React projects including cs-web-proto

Windows Subsystem for Linux (WSL)

This is fairly straightforward once you have WSL installed. Install components such as Git and npm as you would on the Linux distribution that you are using.

This documentation explains how to use VS Code.

Troubleshooting

Using npm install can present problems. I can work around these by closing VS Code whenever I run an npm install command.

Continuous Integration

cs-web-proto uses the github plugins Travis and Coveralls on pushes to validate commits on push. This is used as a prerequisite for merging.

Travis will fail if there are any linting errors in JS or TypeScript files, if any of the unit tests fail or if there are any typescript errors. The tests can be performed locally with:

npm run lint
npm run test
npx tsc

Coverage and Coveralls

Coveralls provides an approximate measure of how much of the code was run from unit tests, although it is far from a perfect metric. If you are contributing, please try to add some unit tests for the changes you make and fix any linting errors or testing errors.

To run all the tests and generate a coverage report locally:

npm test -- --watchAll=false --coverage

Simulating a control system

For local testing, it is convenient to have simulated PVs. See Simulating a control system.

Connecting to EPICS using Coniql

To read and write EPICS PVs, you need a server that can communicate using channel access and / or PVAccess. We use Coniql.

See https://github.com/dls-controls/cs-web-proto/wiki/Running-cs-web-proto-against-Coniql for instructions on how to set up Coniql.

Allowing Remote Access

Having made some awesome changes to the app, it is quite likely you want to show them to other people! Unfortunately, it's not quite as impressive when you say, "Oh you have to come over to MY computer, though". Fortunately, it is possible to expose the app to other machines, and it is quite easy to make your version of the app available within the Diamond network - anyone on the local network, controls network, Diamond VPN or WiFi.

Firstly, find out the hostname of your machine:

$ hostname
mypc.diamond.ac.uk

Then edit .env and add an appropriate port. You may have to include the http:// prefix:

REACT_APP_BASE_URL=http://mypc.diamond.ac.uk:3000

Now when you restart your app, it will not be available through localhost as by default, instead go to http://mypc.diamond.ac.uk:3000 to find your application. The good news is that other people can do this from their machines, phones, tablets, smartwatches, other web-enabled thing, and see your awesome app!

Coniql

Just a note to say that it is perfectly valid to have your app server and coniql server running on two different machines! The coniqlSocket constant does not require the http:// prefix. An example in the .env file:

REACT_APP_BASE_URL=http://mypc.diamond.ac.uk:3000
REACT_APP_CONIQL_SOCKET=otherpc.diamond.ac.uk:8000
Clone this wiki locally