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

@@ -57,8 +57,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
@@ -77,6 +79,49 @@ jobs:
           name: Javascript unit tests coverage
           path: coverage
 
+  package:
+    name: Package ${{ matrix.conditions }}
+    runs-on: ubuntu-latest
+    needs: [build]
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        conditions:
+          - require
+          - import
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Restore dependencies (from cache)
+        uses: actions/cache/restore@v4
+        with:
+          key: npm-install-${{ hashFiles('package-lock.json') }}
+          path: node_modules
+
+      - name: Restore build (from cache)
+        uses: actions/cache/restore@v4
+        with:
+          path: dist/
+          key: build-${{ github.sha }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - name: Resolve entry path
+        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'))" --conditions ${{ matrix.conditions }}
+          node --eval "console.log(require.resolve('nhsuk-frontend/packages/nhsuk.js'))" --conditions ${{ matrix.conditions }}
+          node --eval "console.log(require.resolve('nhsuk-frontend/packages/components/button/button'))" --conditions ${{ matrix.conditions }}
+          node --eval "console.log(require.resolve('nhsuk-frontend/packages/components/button/button.js'))" --conditions ${{ matrix.conditions }}
+
   regression:
     name: Visual regression tests
     runs-on: macos-latest

.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

@@ -7,6 +7,14 @@ jobs:
     name: Dart Sass ${{ matrix.package-version }}
     runs-on: ubuntu-latest
 
+    env:
+      RULE_1: '@import "nhsuk";'
+      RULE_2: '@use "nhsuk" as *;'
+      RULE_3: '@forward "nhsuk";'
+      RULE_4: '@forward "node_modules/nhsuk-frontend/src/nhsuk";'
+      RULE_5: '@forward "node_modules/nhsuk-frontend/src/nhsuk/core/all";'
+      RULE_6: '@forward "pkg:nhsuk-frontend";'
+
     strategy:
       fail-fast: false
 
@@ -35,20 +43,35 @@ jobs:
 
       - name: Install package
         run: |
+          npm install --omit=dev
           npm install -g sass@${{ matrix.package-version }}
           sass --version
 
-      - name: Check compilation
+      - name: Create test files
         run: |
           mkdir -p .tmp
-          time sass packages/nhsuk.scss > .tmp/check.css
+          echo '${{ env.RULE_1 }}' > .tmp/input1.scss
+          echo '${{ env.RULE_2 }}' > .tmp/input2.scss
+          echo '${{ env.RULE_3 }}' > .tmp/input3.scss
+          echo '${{ env.RULE_4 }}' > .tmp/input4.scss
+          echo '${{ env.RULE_5 }}' > .tmp/input5.scss
+          echo '${{ env.RULE_6 }}' > .tmp/input6.scss
+
+      - name: Check compilation
+        run: |
+          time sass packages/nhsuk-frontend/src/nhsuk/nhsuk.scss > .tmp/check.css --load-path .
 
       - name: Check load paths
         run: |
-          mkdir -p .tmp
-          time sh -c 'echo "@import "\""nhsuk"\"";" | sass --stdin --load-path packages > .tmp/check1.css'
-          time sh -c 'echo "@forward "\""nhsuk"\"";" | sass --stdin --load-path packages > .tmp/check2.css'
-          time sh -c 'echo "@use "\""nhsuk"\"" as *;" | sass --stdin --load-path packages > .tmp/check3.css'
+          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/check3.css --load-path .
+          time sass .tmp/input5.scss > .tmp/check3.css --load-path .
+
+      - name: Check package importer
+        run: |
+          time sass .tmp/input6.scss > .tmp/check6.css --pkg-importer node
 
       # Check output for uncompiled Sass
       - name: Check output
@@ -57,3 +80,6 @@ jobs:
           ! grep "\$nhsuk-" .tmp/check1.css
           ! grep "\$nhsuk-" .tmp/check2.css
           ! grep "\$nhsuk-" .tmp/check3.css
+          ! grep "\$nhsuk-" .tmp/check4.css
+          ! grep "\$nhsuk-" .tmp/check5.css
+          ! grep "\$nhsuk-" .tmp/check6.css

README.md

@@ -6,15 +6,9 @@ NHS.UK frontend contains the code you need to start building user interfaces for
 
 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).
 
-## How to install NHS.UK frontend
+## How to install
 
-### 1. Install with package managers
-
-We recommend that you [install NHS.UK frontend using node package manager (npm)](/docs/installation/installing-with-npm.md).
-
-### 2. Install by using compiled files
-
-You can also [install NHS.UK frontend using our compiled files](/docs/installation/installing-compiled.md), if you are not currently using a package manager.
+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

@@ -135,7 +135,7 @@ This enables the NHSUK styles to be used inside other applications, where, for e
 ```scss
 div#nhsuk-ers {
 // ...
-@import "node_modules/nhsuk-frontend/packages/core/all";
+@import "node_modules/nhsuk-frontend/src/nhsuk/core/all";
 // ...
 }
 ```

docs/installation/installing-with-npm.md

@@ -39,17 +39,17 @@ To build the stylesheet you will need a pipeline set up to compile [Sass](https:
 You need to import the NHS.UK frontend styles into the main Sass file in your project. You should place the below code before your own Sass rules (or Sass imports).
 
 ```scss
-@import "node_modules/nhsuk-frontend/packages/nhsuk";
+@import "node_modules/nhsuk-frontend";
 ```
 
 Alternatively you can import each of the individual components separately, meaning you can import just the components that you are using.
 
 ```scss
 // Core (required)
-@import "node_modules/nhsuk-frontend/packages/core/all";
+@import "node_modules/nhsuk-frontend/src/nhsuk/core/all";
 
 // Individual component (optional)
-@import "node_modules/nhsuk-frontend/packages/components/action-link/action-link";
+@import "node_modules/nhsuk-frontend/src/nhsuk/components/action-link/action-link";
 ```
 
 ## Importing JavaScript
@@ -82,30 +82,32 @@ You might wish to copy the file into your project or reference it straight from
   </head>
 ```
 
-### Option 2: Import JavaScript using modules
+### Option 2: Import JavaScript using a bundler
 
-If you're using a transpiler or bundler such as [Babel](https://babeljs.io/) or [Webpack](https://webpack.js.org/), you can use the ES6 import syntax to import components via modules into your main Javascript file.
+We encourage the use of ECMAScript (ES) modules, but you should check your bundler does not unnecessarily downgrade modern JavaScript for unsupported browsers.
+
+If you decide to import using a bundler like [Rollup](https://rollupjs.org/) or [webpack](https://webpack.js.org/), import and run the `initAll` function to initialise NHS.UK frontend:
+
+```js
+import { initAll } from 'nhsuk-frontend'
+initAll()
+```
+
+#### Initialise individual components
+
+Rather than using `initAll`, you can initialise individual components used by your service. For example:
 
 ```js
-// Components
-import Checkboxes from 'nhsuk-frontend/packages/components/checkboxes/checkboxes.js';
-import Details from 'nhsuk-frontend/packages/components/details/details.js';
-import ErrorSummary from 'nhsuk-frontend/packages/components/error-summary/error-summary.js';
-import Header from 'nhsuk-frontend/packages/components/header/header.js';
-import Radios from 'nhsuk-frontend/packages/components/radios/radios.js';
-import SkipLink from 'nhsuk-frontend/packages/components/skip-link/skip-link.js';
+import initRadios from 'nhsuk-frontend/src/nhsuk/components/radios/radios.js';
+import initSkipLink from 'nhsuk-frontend/src/nhsuk/components/skip-link/skip-link.js';
 
 // Polyfills
-import 'nhsuk-frontend/packages/polyfills.js';
+import 'nhsuk-frontend/src/nhsuk/polyfills.js';
 
-// Initialize components
+// Initialise components
 document.addEventListener('DOMContentLoaded', () => {
-  Checkboxes();
-  Details();
-  ErrorSummary();
-  Header();
-  Radios();
-  SkipLink();
+  initRadios();
+  initSkipLink();
 });
 ```