bidlogixteam/app-admin-js repository overview

⁠Admin JS Front-end

⁠Installation

Ensure you are running the correct version of node as specified in the .nvmrc. If you are using nvm⁠, this is as easy as running nvm install within this repo.

Please also ensure that you have yarn⁠ installed. We use yarn for handling our dependencies more efficiently than NPM.

Then, to install dependencies, simply run

yarn

⁠Usage

To use for simple viewing and development, run with

yarn start

Please note, that until we fully tokenise the admin API authentication process, this cannot be run locally. A build script within our devoops repo must be run instead, in order to mount this application within the same domain. This is due to our reliance at this time on sessions for authentication

To build a production-ready bundle

yarn build

To lint

yarn lint

and to test

yarn test

You are also able to test and output coverage with

yarn test --coverage

⁠Implementation Information

⁠Caching and Service Workers

We use service workers to handle caching of our static assets (JS and CSS).

This has advantages over HTTP caching as described here: https://developers.google.com/web/showcase/2016/service-worker-perf⁠

Doing this means that the JS and CSS will always be served up to a returning user, and they will always load the assets which were up to date as of their previous visit. Once loaded, we then check for updated assets, and if they exist, we perform an immediate reload.

This has the disadvantage of a visual reload on the first visit after a release / deploy, but has the advantage of significant load time improvements across all supported devices, and serving up these files even without any network connection (we can leverage this later, to give a better offline experience)

⁠Asset Chunking

Our build will break up our Javascript files into chunks, one per page. This file is only downloaded upon visit to each relevant page.

This means that someone who doesn't have permission for system administration will never even need to download that part of that application. It also allows first-time loads to be significantly faster.

⁠Stateful containers and Functional components

Our React containers are stateful, meaning that they are directly connected to our state store. Through middleware, they have knowledge of our state structure. These containers then pass down all relevant state to child components which are stricly functional.

Doing this means that our components are very easily testable and reusable. They take in props, and return a consistent view every time, without side effects.

⁠Redux and One-way data flow

We use Redux⁠ for our state management, along with a strict one-way data flow.

This means that all data is stored in a single state store, and passed down through our component tree. Actions (functions which cause a state change) then create a new version of the state at the root level, and causes a re-render on all effected components.

What this allows is components which will always have consistent behaviour regardless of where they are placed, and more generic components which we can re-use throughout our application

⁠Bootstrap 4

Bootstrap 4⁠ has been used through ReactStrap⁠, a react-bootstrap 4 library.

Where possible we are using bootstrap-only styles modified through the adjustment of variables.

⁠Data Tables

React Virtualised⁠ is used for our non-standard component layouts such as the Bid Table. This enables us to make performant and flexible layouts regardless of the size of the contents. This is a very powerful library, and can take a bit to grasp.

⁠Unit Testing

We use Jest⁠ as our test runner, with Enzyme⁠ as our React testing utilities.

Some good examples of how we can write tests can be found here: https://redux.js.org/recipes/writing-tests⁠

⁠Sonar Scan

On commit and push to Bitbucket, we run a Sonar Scan to check for code quality, coverage and more. If pushed on a non-develop branch, the scan will be done as if the intent were to eventually be merged back into develop.

Also worth noting is that the scan is done with the version number specified in the package.json as a marker. This allows us to see code quality changes per branch and per version.

⁠API Error Handling

As we are currently utilising many legacy API endpoints which aren't RESTful or standardised, we do not yet receive HTTP error codes on most errors. In order to detect if a session has expired or if there has been an internal error, we simply check our API responses to see if they are of a type application/json. If they are not, we redirect to the legacy login page.

This is not ideal, and will need to be changed in the future once we have refactored the relevant endpoints.