Adopt GOV.UK Frontend packages structure

.github/workflows/actions/build/action.yml

@@ -37,8 +37,10 @@ runs:
       uses: actions/cache/restore@v4
       id: cache-build
       with:
-        path: dist/
         key: build-${{ inputs.ref || github.sha }}
+        path: |
+          dist
+          packages/*/dist
 
     - name: Install dependencies only
       if: ${{ steps.cache-build.outputs.cache-hit == 'true' }}
@@ -56,8 +58,10 @@ runs:
       if: ${{ steps.cache-build.outputs.cache-hit != 'true' }}
       uses: actions/cache/save@v4
       with:
-        path: dist/
         key: build-${{ inputs.ref || github.sha }}
+        path: |
+          dist
+          packages/*/dist
 
     - name: Restore branch or SHA
       if: ${{ !cancelled() && inputs.ref }}

.github/workflows/actions/diff/action.yml

@@ -20,10 +20,15 @@ runs:
       with:
         ref: ${{ github.event.pull_request.base.sha }}
 
+    - name: Copy base build (legacy) into workspace
+      if: ${{ hashFiles('dist/app') != '' }}
+      shell: bash
+      run: mv dist/app packages/nhsuk-frontend-review/dist
+
     - name: Commit base build for comparison
       shell: bash
       run: |
-        git add --force dist/
+        git add --force packages/nhsuk-frontend-review/dist
         git commit --allow-empty -m "Build output for '${{ github.base_ref }}'" --no-verify
 
     - name: Install and build head
@@ -32,14 +37,14 @@ runs:
     - name: Commit head build for comparison
       shell: bash
       run: |
-        git add --force dist/
+        git add --force packages/nhsuk-frontend-review/dist
         git commit --allow-empty -m "Build output for '${{ github.head_ref }}'" --no-verify
 
     - name: Check for changes
       id: diff
       shell: bash
       run: |
         set +e
-        git diff HEAD^ --exit-code --quiet -- 'dist/**/*'
+        git diff HEAD^ --exit-code --quiet -- 'packages/nhsuk-frontend-review/dist/**/*'
         [ $? -eq 0 ] && echo "changes=false" >> "${GITHUB_OUTPUT}"
         exit 0

.github/workflows/deploy.yml

@@ -67,7 +67,7 @@ jobs:
       - name: Upload GitHub Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: dist/app
+          path: packages/nhsuk-frontend-review/dist
 
       - name: Deploy to GitHub Pages
         uses: actions/deploy-pages@v4

.github/workflows/pull-request.yml

@@ -66,8 +66,10 @@ jobs:
       - name: Restore build (from cache)
         uses: actions/cache/restore@v4
         with:
-          path: dist/
           key: build-${{ github.sha }}
+          path: |
+            dist
+            packages/*/dist
 
       - name: Setup Node
         uses: actions/setup-node@v4
@@ -124,8 +126,8 @@ jobs:
         run: |
           node --eval "console.log(require.resolve('nhsuk-frontend'))" --conditions ${{ matrix.conditions }}
           node --eval "console.log(require.resolve('nhsuk-frontend/package.json'))" --conditions ${{ matrix.conditions }}
-          node --eval "console.log(require.resolve('nhsuk-frontend/packages/nhsuk.mjs'))" --conditions ${{ matrix.conditions }}
-          node --eval "console.log(require.resolve('nhsuk-frontend/packages/components/button/button.mjs'))" --conditions ${{ matrix.conditions }}
+          node --eval "console.log(require.resolve('nhsuk-frontend/src/nhsuk/nhsuk.mjs'))" --conditions ${{ matrix.conditions }}
+          node --eval "console.log(require.resolve('nhsuk-frontend/src/nhsuk/components/button/button.mjs'))" --conditions ${{ matrix.conditions }}
 
   regression:
     name: Visual regression tests

.github/workflows/release.yml

@@ -62,6 +62,6 @@ jobs:
           asset_content_type: application/zip
 
       - name: Publish npm package
-        run: npm publish
+        run: npm publish --workspace nhsuk-frontend
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

.github/workflows/sass.yml

@@ -20,9 +20,9 @@ jobs:
       RULE_1: '@import "nhsuk";'
       RULE_2: '@use "nhsuk" as *;'
       RULE_3: '@forward "nhsuk";'
-      RULE_4: '@forward "node_modules/nhsuk-frontend/packages/nhsuk";'
-      RULE_5: '@forward "node_modules/nhsuk-frontend/packages/core";'
-      RULE_6: '@forward "node_modules/nhsuk-frontend/packages/core/all";'
+      RULE_4: '@forward "node_modules/nhsuk-frontend/src/nhsuk";'
+      RULE_5: '@forward "node_modules/nhsuk-frontend/src/nhsuk/core";'
+      RULE_6: '@forward "node_modules/nhsuk-frontend/src/nhsuk/core/all";'
       RULE_7: '@forward "pkg:nhsuk-frontend";'
 
     strategy:
@@ -70,13 +70,13 @@ jobs:
 
       - name: Check compilation
         run: |
-          time sass packages/nhsuk.scss > .tmp/check.css --load-path .
+          time sass packages/nhsuk-frontend/src/nhsuk/nhsuk.scss > .tmp/check.css --load-path .
 
       - name: Check load paths
         run: |
-          time sass .tmp/input1.scss > .tmp/check1.css --load-path packages
-          time sass .tmp/input2.scss > .tmp/check2.css --load-path packages
-          time sass .tmp/input3.scss > .tmp/check3.css --load-path packages
+          time sass .tmp/input1.scss > .tmp/check1.css --load-path packages/nhsuk-frontend/src
+          time sass .tmp/input2.scss > .tmp/check2.css --load-path packages/nhsuk-frontend/src
+          time sass .tmp/input3.scss > .tmp/check3.css --load-path packages/nhsuk-frontend/src
           time sass .tmp/input4.scss > .tmp/check4.css --load-path .
           time sass .tmp/input5.scss > .tmp/check5.css --load-path .
           time sass .tmp/input6.scss > .tmp/check6.css --load-path .

README.md

@@ -4,14 +4,11 @@ NHS.UK frontend contains the code you need to start building user interfaces for
 
 ## Guidance
 
-Visit the [NHS digital service manual](https://service-manual.nhs.uk/) for examples of components and guidance for when to use them. If we haven't yet published guidance on the component you want, please [email us](mailto:service-manual@nhs.net) or get in touch on the [NHS digital service manual Slack workspace](https://join.slack.com/t/nhs-service-manual/shared_invite/enQtNTIyOTEyNjU3NDkyLTk4NDQ3YzkwYzk1Njk5YjAxYTI5YTVkZmUxMGQ0ZjA3NjMyM2ZkNjBlMWMxODVjZjYzNzg1ZmU4MWY1NmE2YzE).
+Visit the [NHS digital service manual](https://service-manual.nhs.uk/) for examples of components and guidance for when to use them. If we haven’t yet published guidance on the component you want, please [email us](mailto:service-manual@nhs.net) or get in touch on the [NHS digital service manual Slack workspace](https://join.slack.com/t/nhs-service-manual/shared_invite/enQtNTIyOTEyNjU3NDkyLTk4NDQ3YzkwYzk1Njk5YjAxYTI5YTVkZmUxMGQ0ZjA3NjMyM2ZkNjBlMWMxODVjZjYzNzg1ZmU4MWY1NmE2YzE).
 
-## Quick start
+## How to install
 
-There are 2 ways to start using NHS.UK frontend in your app:
-
-- [using Node.js package manager (npm)](/docs/installation/installing-with-npm.md) (recommended)
-- by [copying our CSS, JavaScript and asset files into your project](/docs/installation/installing-compiled.md)
+See the [`nhsuk-frontend` README.md](/packages/nhsuk-frontend/README.md) in the packages directory for details.
 
 ## Browsers and assistive technology
 

docs/contributing/application-architecture.md

@@ -1,17 +1,13 @@
 # Application architecture
 
-The application generates static HTML pages to preview components, with each component having their own page, these files can be found in `app/`. To make changes to components, you will have to edit the individual components files within `packages/`. These are usually the only 2 folders that you will need.
+The application generates static HTML pages to preview components, with each component having their own page, these files can be found in `packages/nhsuk-frontend-review/`. To make changes to components, you will have to edit the individual components files within `packages/nhsuk-frontend/`. These are usually the only 2 folders that you will need.
 
 ---
 
 - `.github/`
 
   GitHub specific files, such templates for pull requests and issues.
 
-- `app/`
-
-  Nunjuck (HTML) files for the component example pages that you see at http://localhost:3000/nhsuk-frontend when running the application locally and on https://nhsuk.github.io/nhsuk-frontend
-
 - `dist/` (Automatically generated)
 
   Automatically generated compiled files and build assets for GitHub pages, releases and npm packages. Don't manually edit files in this folder as they will be deleted.
@@ -26,7 +22,28 @@ The application generates static HTML pages to preview components, with each com
 
 - `packages/`
 
-  NHS.UK frontend individual components files, such as all the stylesheet (scss) files, HTML templates (nunjucks), READMEs and assets.
+  - `nhsuk-frontend-review`
+
+    - `dist/` **contains auto-generated files**
+
+      Builds of nhsuk-frontend-review served by [GitHub Pages](https://pages.github.com).
+
+    - `src/`
+
+      Nunjuck (HTML) files for the component example pages that you see at http://localhost:3000/nhsuk-frontend when running the application locally and on https://nhsuk.github.io/nhsuk-frontend
+
+  - `nhsuk-frontend`
+
+    Package published on npm.
+    Consume all of nhsuk-frontend through a single package.
+
+    - `dist/` **contains auto-generated files**
+
+      Builds of nhsuk-frontend published and exported from the npm package.
+
+    - `src/`
+
+      NHS.UK frontend individual components files, such as all the stylesheet (scss) files, HTML templates (nunjucks), READMEs and assets.
 
 - `shared/`
 

docs/contributing/coding-standards.md

@@ -137,7 +137,7 @@ This enables the NHSUK styles to be used inside other applications, where, for e
 
 div#nhsuk-ers {
   // ...
-  @include meta.load-css("node_modules/nhsuk-frontend/packages/core");
+  @include meta.load-css("node_modules/nhsuk-frontend/src/nhsuk/core");
   // ...
 }
 ```
@@ -287,7 +287,7 @@ Care card emergency (red and black) example:
 
 ## Components
 
-You can find NHS.UK frontend components in `packages/components`.
+You can find NHS.UK frontend components in `packages/nhsuk-frontend/src/nhsuk/components`.
 
 Components must use the `.nhsuk-` namespace.
 

docs/installation/installing-with-npm.md

@@ -44,13 +44,13 @@ You must add the root of your application to Sass load paths, by either:
 Then load the NHS.UK frontend styles by adding the following to your Sass file. You should place the below code before your own Sass rules (or Sass `@forward`).
 
 ```scss
-@forward "node_modules/nhsuk-frontend/packages/nhsuk";
+@forward "node_modules/nhsuk-frontend/src/nhsuk";
 ```
 
 Alternatively you can use NHS.UK frontend styles with a custom configuration:
 
 ```scss
-@forward "node_modules/nhsuk-frontend/packages/nhsuk" with (
+@forward "node_modules/nhsuk-frontend/src/nhsuk" with (
   $nhsuk-include-font-face: false
 );
 ```
@@ -59,10 +59,10 @@ Or to use only the minimum components necessary:
 
 ```scss
 // Core (required)
-@forward "node_modules/nhsuk-frontend/packages/core";
+@forward "node_modules/nhsuk-frontend/src/nhsuk/core";
 
 // Individual component (optional)
-@forward "node_modules/nhsuk-frontend/packages/components/action-link/action-link";
+@forward "node_modules/nhsuk-frontend/src/nhsuk/components/action-link";
 ```
 
 ## Importing JavaScript
@@ -111,8 +111,8 @@ initAll()
 Rather than using `initAll`, you can initialise individual components used by your service. For example:
 
 ```js
-import { initRadios } from 'nhsuk-frontend/packages/components/radios/radios.mjs';
-import { initSkipLink } from 'nhsuk-frontend/packages/components/skip-link/skip-link.mjs';
+import { initRadios } from 'nhsuk-frontend/src/nhsuk/components/radios/radios.mjs';
+import { initSkipLink } from 'nhsuk-frontend/src/nhsuk/components/skip-link/skip-link.mjs';
 
 // Initialise components
 document.addEventListener('DOMContentLoaded', () => {

gulpfile.mjs

@@ -1,34 +1,39 @@
-import browserSync from 'browser-sync'
-import gulp from 'gulp'
+import { join } from 'path'
 
+import * as config from '@nhsuk/frontend-config'
 import {
   buildHTML,
   validateHTML,
   copyCSS,
   copyJS,
   copyBinaryAssets,
   serve
-} from './shared/tasks/app.mjs'
-import { clean } from './shared/tasks/clean.mjs'
+} from '@nhsuk/frontend-tasks/app.mjs'
+import { clean } from '@nhsuk/frontend-tasks/clean.mjs'
 import {
   assets,
   cssFolder,
   jsFolder,
   createZip
-} from './shared/tasks/release.mjs'
-import { webpackJS, minifyJS } from './shared/tasks/scripts.mjs'
-import { compileCSS, minifyCSS } from './shared/tasks/styles.mjs'
+} from '@nhsuk/frontend-tasks/release.mjs'
+import { webpackJS, minifyJS } from '@nhsuk/frontend-tasks/scripts.mjs'
+import { compileCSS, minifyCSS } from '@nhsuk/frontend-tasks/styles.mjs'
+import browserSync from 'browser-sync'
+import gulp from 'gulp'
 
 /**
  * Development tasks
  */
 
 gulp.task('clean', async () => {
-  return clean(['dist/**/*'])
+  return clean([join(config.paths.root, 'dist/**/*')])
 })
 
 gulp.task('clean:zip', async () => {
-  return clean(['dist/{assets,css,js}', 'dist/*.zip'])
+  return clean([
+    join(config.paths.root, 'dist/{assets,css,js}'),
+    join(config.paths.root, 'dist/*.zip')
+  ])
 })
 
 gulp.task('style', gulp.series([compileCSS, minifyCSS]))
@@ -47,8 +52,14 @@ gulp.task(
 
 gulp.task('watch', () =>
   Promise.all([
-    gulp.watch(['packages/**/*.scss'], gulp.series(['style'])),
-    gulp.watch(['packages/**/*.mjs'], gulp.series(['script']))
+    gulp.watch(
+      [join(config.paths.pkg, 'src/nhsuk/**/*.scss')],
+      gulp.series(['style'])
+    ),
+    gulp.watch(
+      [join(config.paths.pkg, 'src/nhsuk/**/*.mjs')],
+      gulp.series(['script'])
+    )
   ])
 )
 
@@ -63,11 +74,37 @@ gulp.task(
 
 gulp.task('docs:watch', () =>
   Promise.all([
-    gulp.watch(['app/**/*.njk', 'packages/**/*.njk'], buildHTML),
-    gulp.watch(['dist/**/*.html']).on('change', browserSync.reload),
-    gulp.watch(['dist/*.min.{css,css.map}'], copyCSS),
-    gulp.watch(['dist/*.min.{js,js.map}'], copyJS),
-    gulp.watch(['packages/assets/**/*'], copyBinaryAssets)
+    /**
+     * Watch and render Nunjucks
+     */
+    gulp.watch(
+      [
+        join(config.paths.app, 'src/**/*.njk'),
+        join(config.paths.pkg, 'src/nhsuk/**/*.njk')
+      ],
+      buildHTML
+    ),
+
+    /**
+     * Watch and reload HTML pages
+     */
+    gulp
+      .watch([join(config.paths.root, 'dist/**/*.html')])
+      .on('change', browserSync.reload),
+
+    /**
+     * Watch and copy minified CSS and JS
+     */
+    gulp.watch([join(config.paths.root, 'dist/*.min.{css,css.map}')], copyCSS),
+    gulp.watch([join(config.paths.root, 'dist/*.min.{js,js.map}')], copyJS),
+
+    /**
+     * Watch and copy assets
+     */
+    gulp.watch(
+      [join(config.paths.pkg, 'src/nhsuk/assets/**/*')],
+      copyBinaryAssets
+    )
   ])
 )