Ivory front office

Digital service to support the Ivory Act.

(Please note that this service is best installed as part of the Ivory root project)

Development Team

This module was developed by the Ivory team as part of a digital transformation project at DEFRA, a department of the UK government

Prerequisites

Please make sure the following are installed:

• Git
• Node.js v10/Dubnuim recommend installing nvm and using nvm install 10
• StandardJS using npm install -g standard

Check that your environment is running the correct versions of node and npm:

$ npm --version
6.13.4
$ node --version
v10.18.1

Please note that this project needs to be configured to access an instance of the ivory-services REST service

Installation

The best way to work on this project is by installing the multi-project ivory with all three of the ivory services installed locally.

If you still want to work on this project individually then clone the repository and install its package dependencies:

git clone https://github.com/DEFRA/ivory-front-office.git && cd ivory-front-office
npm install

Setting up .env

Copy the .env.example file to .env and set it up for your environment

cp .env.example .env

Running the app

Make sure the ivory-services service is running prior to starting the app

Run the app using npm

npm start

Unit testing the app

Use the following npm task. This runs the StandardJS linting as well as the unit tests to produce a coverage.html report

npm test

Check the server is running by pointing your browser to http://localhost:3000

Plugins

hapi has a powerful plugin system and as much server code as possible should be loaded in a plugin.

Plugins live in the server/plugins directory.

Logging

The good and good-console plugins are included and configured in server/plugins/logging

The logging plugin is only registered in when NODE_ENV=development.

Error logging for production should use errbit.

Views

The hapi-govuk-frontend plugin is used for GDS Design system nunjucks template rendering support.

The template engine used is nunjucks inline with the GDS Design System with support for view caching, layouts, partials and helpers.

Static files

The Inert plugin is used for static file and directory handling in hapi.js. Put all static assets in server/public/static.

Any build output should write to server/public/build. This path is in the .gitignore and is therefore not checked into source control.

Routes and flow

Incoming requests are handled by the server via routes. Each route describes an HTTP endpoint with a path, method, and other properties. The configuration for these routes can be found in server/flow.yml

The handlers for these routes are found within their relevant feature/module in the server/modules directory and loaded using the server/plugins/flow.js plugin.

See the defra-hapi-route-flow module/plugin, for more information

Resources

There are lots of route options, here's the documentation on hapi routes

Tasks

Build tasks are created using simple shell scripts or node.js programs. The default ones are found in the bin directory.

The task runner is simply npm using npm-scripts.

We chose to use this for simplicity but there's nothing to stop you adding gulp, grunt or another task runner if you prefer.

The predefined tasks are:

• npm run build (Runs all build sub-tasks)
• npm run build:css (Builds the client-side sass)
• npm run lint (Runs the lint task using standard.js)
• npm run unit-test (Runs the lab tests in the /test folder)
• npm test (Runs the lint task then the unit-tests)

Resources

For more information around using npm-scripts as a build tool:

• http://substack.net/task_automation_with_npm_run
• http://ponyfoo.com/articles/choose-grunt-gulp-or-npm
• http://blog.keithcirkel.co.uk/why-we-should-stop-using-grunt/
• http://blog.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/

Testing

lab and code are used for unit testing.

Note that the .labrc.js file is configured to allow the test scripts to sit within the same directories as the js file they are testing.

Linting

standard.js is used to lint both the server-side and client-side javascript code.

It's defined as a build task and can be run using npm run lint.

License

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the license

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.