Merge pull request #3725 from alphagov/build-default

Add default “npm run build” for project (with docs updates)

.github/workflows/screenshots.yml

@@ -41,7 +41,7 @@ jobs:
       - name: Build
         uses: ./.github/workflows/actions/build
 
-      - name: Start review application
+      - name: Start review app
         run: npm start --workspace govuk-frontend-review &
 
       - name: Send screenshots to Percy

docs/contributing/application-architecture.md

@@ -16,7 +16,23 @@
 
   - `govuk-frontend-review/`
 
-    [Express](https://github.com/expressjs/express) application to preview components; also referred to as the _review app_.
+    [Express.js](https://github.com/expressjs/express) review app [deployed to Heroku](https://govuk-frontend-review.herokuapp.com) with configuration in [app.json](/app.json) and [Procfile](/Procfile).
+
+    - `dist/` **contains auto-generated files**
+
+      Builds of govuk-frontend-review served by [Express.js](https://github.com/expressjs/express).
+
+    - `src/`
+
+      Source files for component previews and examples.
+
+    - `tasks/`
+
+      Read about [npm and Gulp tasks](tasks.md) or list workspace specific Gulp tasks using:
+
+      ```shell
+      npx --workspace govuk-frontend-review -- gulp --tasks
+      ```
 
   - `govuk-frontend/`
 
@@ -29,7 +45,15 @@
 
     - `src/`
 
-    Source files. See [README.md](/packages/govuk-frontend/src/README.md) in the src directory for details.
+      Source files. See [README.md](/packages/govuk-frontend/src/README.md) in the src directory for details.
+
+    - `tasks/`
+
+      Read about [npm and Gulp tasks](tasks.md) or list workspace specific Gulp tasks using:
+
+      ```shell
+      npx --workspace govuk-frontend -- gulp --tasks
+      ```
 
 - `shared/`
 
@@ -49,4 +73,4 @@
 
   - `tasks/`
 
-    See [tasks](tasks.md) for more information about the tasks.
+    Read about [npm and Gulp tasks](tasks.md) for more information about the tasks.

docs/contributing/tasks.md

@@ -1,29 +1,29 @@
 # npm and Gulp tasks
 
-This document describes the npm scripts that run the application, and the Gulp tasks they trigger to build files, update the package, copy assets and watch for changes.
+This document describes the npm scripts that run the Express.js review app, and the Gulp tasks they trigger to build files, update the package, copy assets and watch for changes.
 
-To run the application without any tasks being triggered, see [Express app only](#express-app-only).
+To run the Express.js review app without any tasks being triggered, see [Review app only](#review-app-only).
 
 ## npm script aliases
 
 npm scripts are defined in `package.json`. These trigger a number of Gulp tasks.
 
 **`npm start` will trigger `npm run dev` that will:**
 
-- runs tasks from `npm run build:package`
-- runs tasks from `npm run build:app`
-- starts up Express, restarting when `.mjs`, `.json` or `.yaml` files change
+- runs `npm run build`
+- starts the review app, restarting when `.mjs`, `.json` or `.yaml` files change
 - compile again when frontend `.mjs` and `.scss` files change
 
 **`npm test` will do the following:**
 
 - run Nunjucks macros tests
-- run JavaScript tests on the review application
+- run JavaScript tests on the review app
 - run accessibility and HTML validation tests
 
-**`npm run serve --workspace govuk-frontend-review` will do the following:**
+**`npm run build` will do the following:**
 
-- start up Express, restarting when `.mjs`, `.json` or `.yaml` files change
+- run tasks from `npm run build:package`
+- run tasks from `npm run build:app`
 
 **`npm run build:app` will trigger `npm run build --workspace govuk-frontend-review` that will:**
 
@@ -74,7 +74,7 @@ GOV.UK Frontend package build Gulp tasks are defined in [`packages/govuk-fronten
 
 **`npx --workspace govuk-frontend -- gulp --tasks`**
 
-This will list out all available tasks for the Review app.
+This will list out all available tasks for the review app.
 
 Review app Gulp tasks are defined in [`packages/govuk-frontend-review/gulpfile.mjs`](/packages/govuk-frontend-review/gulpfile.mjs) and the [`packages/govuk-frontend-review/tasks/`](/packages/govuk-frontend-review/tasks) folder.
 
@@ -94,6 +94,6 @@ This task will:
 - compile JavaScript to Universal Module Definition (UMD) into `./packages/govuk-frontend-review/dist/javascripts`
 - compile JavaScript documentation into `./packages/govuk-frontend-review/dist/docs/jsdoc`
 
-## Express app only
+## Review app only
 
-To start the Express app without Gulp tasks being triggered, run `npm run serve`.
+After building the project with `npm run build` the Express.js review app can be started with `npm start --workspace govuk-frontend-review`. This prevents the Gulp tasks triggered by `npm start` from running.

package.json

@@ -20,17 +20,18 @@
     "build-release": "./bin/build-release.sh",
     "publish-release": "./bin/publish-release.sh",
     "pre-release": "./bin/pre-release.sh",
-    "predev": "npm run build --workspace govuk-frontend",
+    "predev": "npm run build",
     "dev": "concurrently \"npm run dev --workspace govuk-frontend-review\" \"npm run dev --workspace govuk-frontend\" --kill-others --names \"app,pkg\" --prefix-colors \"red.dim,blue.dim\"",
+    "build": "npm run build --workspace govuk-frontend --workspace govuk-frontend-review",
     "build:app": "npm run build --workspace govuk-frontend-review",
     "build:package": "npm run build:package --workspace govuk-frontend",
     "build:release": "npm run build:release --workspace govuk-frontend",
     "build:types": "tsc --build tsconfig.json tsconfig.build.json",
     "postbuild:package": "jest --color --selectProjects \"Build tasks\" --testMatch \"**/*package.test*\"",
     "postbuild:release": "jest --color --selectProjects \"Build tasks\" --testMatch \"**/*release.test*\"",
-    "heroku-postbuild": "npm run build --workspace govuk-frontend --workspace govuk-frontend-review",
+    "heroku-postbuild": "npm run build",
     "postheroku-postbuild": "NPM_CONFIG_PRODUCTION=true npm ci --ignore-scripts --omit=optional --workspace govuk-frontend-review",
-    "pretest": "npm run build --workspace govuk-frontend --workspace govuk-frontend-review",
+    "pretest": "npm run build",
     "test": "jest --color --ignoreProjects \"Build tasks\" --maxWorkers=50%",
     "lint": "npm run lint:editorconfig && npm run lint:prettier && npm run lint:js && npm run lint:scss",
     "lint:editorconfig": "npm run lint:editorconfig:cli",

packages/govuk-frontend-review/package.json

@@ -9,7 +9,6 @@
   },
   "license": "MIT",
   "scripts": {
-    "predev": "npm run build",
     "dev": "gulp dev --color",
     "build": "gulp build --color",
     "build:sassdoc": "sassdoc --config sassdoc.config.yaml ../govuk-frontend/src/govuk",

packages/govuk-frontend-review/src/common/nunjucks/index.mjs

@@ -18,7 +18,7 @@ export function renderer (app) {
   // Initialise nunjucks environment
   const env = nunjucks.configure(appViews, {
     autoescape: true, // output with dangerous characters are escaped automatically
-    express: app, // the express app that nunjucks should install to
+    express: app, // the Express.js review app that nunjucks should install to
     noCache: true, // never use a cache and recompile templates each time
     trimBlocks: true, // automatically remove trailing newlines from a block/tag
     lstripBlocks: true, // automatically remove leading whitespace from a block/tag

shared/config/paths.js

@@ -12,6 +12,6 @@ module.exports = {
   // Package for npm publish
   package: join(rootPath, 'packages/govuk-frontend'),
 
-  // Review application
+  // Express.js review app
   app: join(rootPath, 'packages/govuk-frontend-review')
 }

shared/config/ports.js

@@ -1,5 +1,5 @@
 /**
- * Review application ports
+ * Express.js review app ports
  */
 module.exports = {
   app: process.env.PORT || 8080