Welcome to your Sprint UI app

Hello Sprint UI ❯❯❯👟❯❯👟❯

This project was generated by Sprint UI. You can find out more about this blazing fast site generator here.

The main scope of this project is to streamline traditional UI stack (HTML + CSS + JS) workflows and incorporate best practices for NHSUK and GOVUK projects - but also for vanilla projects.

The project uses Gulp 4, Webpack 4, Node SASS and Babel to build production-ready front-end assets using the NHSUK or GOVUK - or no toolkit at all if you need a blank canvas for your project. The project is also a static site gerenator - creating HTML pages from Nunjucks templates.

The great thing about this app is that it can function both as a lean, standalone application (e.g. a Node app for prototyping locally and user testing via Heroku), but it can also be added to a larger, more robust application (such as a Spring Java app) - and be used just to generate assets for production environment.

❯❯❯ This is not the official NHSUK/GOVUK prototyping toolkit

If you generated a this site using the NHSUK or GOVUK generator of Sprint UI, it is worth noting, that can use this project to build or prototype a NHSUK or GOVUK service, but this is not the official NHSUK or GOVUK prototyping toolkit, and it is not maintained by the GDS, NHSUK or GOVUK developers.

However, I made a conscious effort to keep the codebase as similar to the protyping toolkits as possible, so you can use the macros, components and templating just like in the official prototyping toolkits, with the exception of the routing and the data storage features are missing from this one.

If you need any help with the components or the templating, just refer to the official documentation, as it works ~100% the same.

GovUK Design System - Components: https://design-system.service.gov.uk/components
NHSUK Design System - Components: https://service-manual.nhs.uk/design-system/components

❯❯❯ Requirements

The project requries NodeJS 10 or newer.

❯❯❯ Demo

https://statik-ui.herokuapp.com/

USERNAME: bruceWayne
PASSWORD: iWearTights

❯❯❯ Production-ready asset generation

The criteria for production-ready assets are:

Multiple source-files (to encourage modular coding) for stylesheets and javascript coding
Single CSS and JavaScript output generated from those source files
The output files are minified, uglified and (potentially revved for no-cache purposes)
We do this to reduce the amount of HTTP requests the application makes in the production environment. Less HTTP requests = quicker page loading time

❯❯❯ Current status of the project

Primarily this app can be used to build the front-end for an NHSUK/GOVUK application, and to build production-ready static assets for that application. While this is not the official prototyping toolkit (read more about this below), the application can be used for prototyping, as the prototype can be developed and used both locally, or remotely by deploying to Heroku, where password protection is supported via basic authentication.

Check the developer notes below for planned future improvements.

❯❯❯ Installing the project

Better/faster/more reliable with yarn, but you can just use npm if you want...

$ yarn|npm install

❯❯❯ Generate production ready files

$ yarn|npm build-prod

The output will be minified, uglified, concatenated into the lest amount of files - ready for production.

The generated files are spit out into the following structure:

public
|_assets
  |_css
  |_favicons (automatically added from NHSUK front-end)
  |_fonts
  |_icons (automatically added from NHSUK front-end)
  |_images
  |_js
  |_logos (automatically added from NHSUK front-end)
|_html (static HTML files)

❯❯❯ Build things locally

This is great, if you want to develop something. This command will launch the site on (localhost:3000)[http://localhost:3000] with BrowserSync, so you can build things ⚡ quickly, and test the site across multiple devices at once.

$ yarn|npm dev

❯❯❯ Generate files in local development mode

The output in dev mode will be still single files, but with source maps and human readable - perfect for debugging!

$ yarn|npm build-dev

❯❯❯ Deploying to Heroku

❯❯ Setting up Heroku

You will need a Heroku account first.

Then you'll need to install Heroku CLI.

Once you authenticated yourself you're ready to create your Heroku app using Heroku CLI (or just use the Heroku dashboard in the browser).

❯❯ Create new Heroku app

You can create a new application in the Heroku web dashboard, or using the command line:

$ heroku apps:create my-heroku-app -r heroku --region eu

❯❯ Push to Heroku using master branch

$ git push heroku master

❯❯ Push to Heroku using feature branch

$ git push -f heroku featureBranchName:master

❯❯❯ Debugging Heroku

To see the logs you can use HerokuCLI:

$ heroku logs --tail

❯❯❯ Protecting your Heroku site

It is important to remember, that you MUST protect your Heroku site if your site or prototype uses any ports of the NHSUK or GOVUK front-end libraries to make sure that noone from the public mistakens your site for an actual public service site.

❯❯ Set up the environment variables for the basic authentication

$ heroku config:set USERNAME=BRUCE_WAYNE
$ heroku config:set PASSWORD=I_WEAR_TIGHTS_AT_NIGHT

❯❯❯ Developer notes

Imagemin has a dependency called jpegtran, which is a little flaky, and occassionally it can fail the image processing https://gist.github.com/welcoMattic/9f0991fa81a80096a3877ee42562c504. If you see a Gulp error caused by jpegtran, just rebuild the binary:
```
  $ npm rebuild jpegtran-bin
```
Node SASS can lose its binding to the operating system. When that ocassionally happens rebuild the binary to resolve the issue by running:
```
  $ npm rebuild node-sass
```
There are SASS and ES (JavaScript) linting tasks in the Gulp file, but to keep things streamlined and to be able to iterate rapidly these are switched off for now.

❯❯❯ Planned actions (to do)

Add configurable basic authentication for Heroku deployments ✅
Document Heroku deployment process ✅
Replace unmaintained SASS-Lint with SCSS-Lint
Configure SCSS-lint using sensible defaults
Configure ESLint using sensible defaults
Clean up NPM dependencies ✅
Tidy up the Gulp file
Enable the direct use of underlying (NHSUK) front-end toolkit macros and other resources ✅
Add data and routing to the server
Add setup script, so that the developer can chose between GOVUK and NHSUK design system

robpataki/sprint-ui-nhsuk