Merge pull request #162 from hmrc/PLATUI-1190_publish_hmrc_frontend_w…

…ebjar

PLATUI-1190: Build a webjar

.eslintrc.json

@@ -11,6 +11,8 @@
     "backstop_data/**/*",
     "sassdoc/**/*",
     "package/**/*",
+    "webjar/**/*",
+    "webjar-dist/**/*",
     "public/**/*",
     "dist/**/*"
   ],

.gitignore

@@ -41,3 +41,6 @@ __tests__/hmrc-frontend
 backstop_data/bitmaps_test/*
 backstop_data/html_report/*
 
+webjar/
+webjar-dist/
+

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## Changed
+
+- Added task to build and publish a webjar for Scala libraries and microservices
+
 ## [1.35.2] - 2021-05-24
 
 ## Fixed

CONTRIBUTING.md

@@ -214,3 +214,49 @@ All work on GOV.UK should [use progressive enhancement](https://www.gov.uk/servi
 Services on GOV.UK are for the benefit of all users. This means you must build a service that’s as inclusive as possible.
 
 [Accessibility guidance on GOV.UK](https://www.gov.uk/service-manual/helping-people-to-use-your-service/making-your-service-accessible-an-introduction).
+
+### Code Style (Linting)
+
+We use tools to ensure the style of our SCSS and JS is consistent.  The code is checked when the tests
+run on the build server.  If you are contributing SCSS or JS you'll probably be running
+the tests using `npm test` - this includes the code style checks.
+
+To run the code style checks independently you can run `npm run lint`.
+
+Automatic fixing is available for a number of the code style rules we apply.  To let the tool
+automatically fix the issues it can fix run `npm run lint:fix` - that will show you any remaining
+issues after the tool has fixed what it can for you.
+
+### WebJar publishing
+
+In order to make the hmrc-frontend assets easy to consume in a JVM environment,
+the npm `build:webjar` task builds a JVM compatible webjar. This webjar is published to HMRC's open
+artefact repository by an internal automated deployment process and is a dependency of
+[hmrc/play-frontend-hmrc](https://www.github.com/hmrc/play-frontend-hmrc).
+
+When testing changes in conjunction with `play-frontend-hmrc` and consuming frontend microservices,
+it's possible to publish the hmrc-frontend webjar locally as follows. You will need Java and [Maven](https://maven.apache.org/install.html)
+installed.
+
+```bash
+npm run build:package
+npm run build:webjar
+npm run publish-local:webjar
+```
+
+You can then reference the webjar in the `LibDependencies.scala` file in `play-frontend-hmrc` as follows:
+
+```sbt
+"uk.gov.hmrc.webjars" % "hmrc-frontend" % "X.Y.Z"
+```
+
+You will also need to configure your `build.sbt` resolvers to look in your local Maven repository:
+
+```sbt
+resolvers += Resolver.mavenLocal
+```
+
+Further documentation on the webjar mechanism can be found:
+
+* https://www.webjars.org/documentation
+* https://www.playframework.com/documentation/2.8.x/AssetsOverview

README.md

@@ -55,18 +55,6 @@ If you would like to propose a feature or raise an issue with HMRC Frontend, [cr
 
 You can also create a pull request to contribute to HMRC Frontend. See our [contribution process and guidelines for HMRC Frontend](CONTRIBUTING.md) before you create a pull request.
 
-### Code Style (Linting)
-
-We use tools to ensure the style of our SCSS and JS is consistent.  The code is checked when the tests
-run on the build server.  If you are contributing SCSS or JS you'll probably be running
-the tests using `npm test` - this includes the code style checks.
-
-To run the code style checks independently you can run `npm run lint`.
-
-Automatic fixing is available for a number of the code style rules we apply.  To let the tool
-automatically fix the issues it can fix run `npm run lint:fix` - that will show you any remaining
-issues after the tool has fixed what it can for you.
-
 ## License
 
 This code is open source software licensed under the [Apache 2.0 License]("http://www.apache.org/licenses/LICENSE-2.0.html").

gulpfile.js

@@ -1,4 +1,4 @@
-const gulp = require('gulp');
+const { series, parallel } = require('gulp');
 const nodemon = require('nodemon');
 
 require('./tasks/gulp/clean.js');
@@ -11,46 +11,60 @@ require('./tasks/gulp/backstop.js');
 require('./tasks/gulp/package.js');
 require('./tasks/gulp/dist.js');
 
-gulp.task('copy-dist-files', gulp.series(
+const { publishLocalWebjar, buildWebjar } = require('./tasks/gulp/webjar');
+
+const copyDistFiles = series(
   'copy-hmrc-images',
   'copy-govuk-images',
   'copy-govuk-fonts',
   'copy-html5shiv',
-));
+);
 
-gulp.task('copy-package-files', gulp.series(
+const copyPackageFiles = series(
   'copy-package-sources',
   'copy-govuk-fonts',
   'copy-govuk-images',
   'copy-html5shiv',
   'copy-govuk-config',
   'copy-check-compatibility',
-));
+);
 
-gulp.task('build:package', gulp.series(
+const buildPackage = series(
   'clean',
-  'copy-package-files',
+  copyPackageFiles,
   'scss:compile-all-govuk-and-hmrc',
   'js:compile-hmrc',
   'js:compile-all-govuk-and-hmrc',
   'update-assets-version',
   'copy:README',
   'copy:LICENSE',
   'copy:packageJson',
-));
+);
 
-gulp.task('build:dist', gulp.series(
+const buildDist = series(
   'clean',
-  'copy-dist-files',
+  copyDistFiles,
   'scss:compile-all-govuk-and-hmrc',
   'js:compile-all-govuk-and-hmrc',
   'update-assets-version',
-));
+);
 
-gulp.task('backstop:test', gulp.series('build:dist', 'backstop-test'));
+const backstopTest = series(buildDist, 'backstop-test');
 
-gulp.task('nodemon', () => nodemon({
+const startNodemon = () => nodemon({
   script: 'app/start.js',
-}));
+});
+
+const dev = series(buildDist, parallel(startNodemon, 'watch'));
 
-gulp.task('dev', gulp.series('build:dist', gulp.parallel('nodemon', 'watch')));
+// FIXME: fix named tasks above to export rather than using gulp.task, to avoid globally registering
+// tasks unnecessarily
+// See: https://gulpjs.com/docs/en/getting-started/creating-tasks
+module.exports = {
+  buildPackage,
+  buildDist,
+  backstopTest,
+  dev,
+  buildWebjar,
+  publishLocalWebjar,
+};