Investigate using the packages folder convention

.editorconfig

@@ -113,7 +113,7 @@ charset = utf-8
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[{**package**,**vendor**}]
+[{**dist**,**vendor**}]
 indent_size = unset
 indent_style = unset
 charset = unset

.eslintrc.js

@@ -2,7 +2,6 @@ module.exports = {
   extends: 'standard',
   ignorePatterns: [
     '**/dist/**',
-    '**/package/**',
     '**/vendor/**',
 
     // Enable dotfile linting
@@ -77,7 +76,12 @@ module.exports = {
           'never', {
             startLines: 1
           }
-        ]
+        ],
+
+        // Ignore `govuk-frontend` exports as they require auto-generated files
+        'import/no-unresolved': ['error', { ignore: ['govuk-frontend'] }],
+        'n/no-missing-import': ['error', { allowModules: ['govuk-frontend'] }],
+        'n/no-missing-require': ['error', { allowModules: ['govuk-frontend'] }]
       },
       settings: {
         jsdoc: {

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

@@ -11,7 +11,7 @@ runs:
       with:
         # Restore build cache (unless commit SHA changes)
         key: build-cache-${{ runner.os }}-${{ github.sha }}
-        path: app/dist
+        path: packages/*/dist
 
     - name: Install dependencies
       uses: ./.github/workflows/actions/install-node
@@ -26,4 +26,4 @@ runs:
       if: steps.build-cache.outputs.cache-hit != 'true'
       shell: bash
 
-      run: npm run build:app
+      run: npm run build --workspaces --if-present

.github/workflows/actions/install-node/action.yml

@@ -13,9 +13,8 @@ runs:
         key: npm-install-cache-${{ runner.os }}-${{ hashFiles('package-lock.json', '**/package.json') }}
         path: |
           node_modules
-          app/node_modules
           docs/examples/*/node_modules
-          package/node_modules
+          packages/*/node_modules
           shared/*/node_modules
 
     - name: Setup Node.js

.github/workflows/sass.yaml

@@ -36,7 +36,7 @@ jobs:
           sass --version
 
       - name: Run command
-        run: time sass src/govuk/all.scss > /dev/null
+        run: time sass packages/govuk-frontend/src/govuk/all.scss > /dev/null
 
   dart-sass-latest:
     name: Dart Sass v1 (latest)
@@ -64,7 +64,7 @@ jobs:
         # Run the command through a shell to ensure `time` measures the time
         # taken by the entire pipeline, as we are now piping input into `sass`.
       - name: Run command
-        run: time sh -c 'echo "@import "\""govuk/all"\"";" | sass --stdin --quiet-deps --load-path=src > /dev/null'
+        run: time sh -c 'echo "@import "\""govuk/all"\"";" | sass --stdin --quiet-deps --load-path=packages/govuk-frontend/src > /dev/null'
 
   # Node Sass v3.4.0 = LibSass v3.3.0
   lib-sass:
@@ -87,7 +87,7 @@ jobs:
           node-sass --version
 
       - name: Run command
-        run: time node-sass src/govuk/all.scss > /dev/null
+        run: time node-sass packages/govuk-frontend/src/govuk/all.scss > /dev/null
 
   # Node Sass v8.x = LibSass v3 latest
   lib-sass-latest:
@@ -110,7 +110,7 @@ jobs:
           node-sass --version
 
       - name: Run command
-        run: time node-sass src/govuk/all.scss > /dev/null
+        run: time node-sass packages/govuk-frontend/src/govuk/all.scss > /dev/null
 
   ruby-sass:
     name: Ruby Sass v3.4.0 (deprecated)
@@ -131,7 +131,7 @@ jobs:
           sass --version
 
       - name: Run command
-        run: time sass src/govuk/all.scss > /dev/null
+        run: time sass packages/govuk-frontend/src/govuk/all.scss > /dev/null
 
   ruby-sass-latest:
     name: Ruby Sass v3 (latest, deprecated)
@@ -152,4 +152,4 @@ jobs:
           sass --version
 
       - name: Run command
-        run: time sass src/govuk/all.scss > /dev/null
+        run: time sass packages/govuk-frontend/src/govuk/all.scss > /dev/null

.github/workflows/screenshots.yml

@@ -41,10 +41,10 @@ jobs:
         uses: ./.github/workflows/actions/build
 
       - name: Start review application
-        run: npm start --workspace app &
+        run: npm start --workspace packages/govuk-frontend-review &
 
       - name: Send screenshots to Percy
-        run: npx percy exec --parallel -- npm run test:screenshots
+        run: npx percy exec --parallel -- npm run test:screenshots --workspace packages/govuk-frontend-review
 
       - name: Finalise Percy build
         run: npx percy build:finalize

.github/workflows/tests.yml

@@ -159,8 +159,8 @@ jobs:
             run: npm run build:package
 
           - description: Verify distribution build
-            name: test-build-dist
-            run: npm run build:dist
+            name: test-build-release
+            run: npm run build:release
 
           - description: JavaScript behaviour tests
             name: test-behaviour

.lintstagedrc.js

@@ -1,7 +1,7 @@
 const { ESLint } = require('eslint')
 
 module.exports = {
-  // ESLint's configuration makes it ignore built files in `dist` or `package`
+  // ESLint's configuration makes it ignore built files in `dist` or `packages/govuk-frontend/dist`
   // that we want left alone, as well as the polyfills.
   // The glob used by lint-staged to trigger the linting on commit isn't aware
   // of that ignore list, so will ask ESLint to lint those files.

.prettierignore

@@ -11,9 +11,6 @@ coverage/
 # Build output
 dist/
 
-# Build output (committed)
-/package
-
 # 3rd party vendor code
 vendor/
 

CHANGELOG.md

@@ -4,6 +4,63 @@
 
 ### Breaking changes
 
+You must make the following changes when you migrate to this release, or your service may break.
+
+#### Update package file paths
+
+To support package dependencies, we’ve moved our source files from `src` into `packages/govuk-frontend/src`. In preparation for additional build targets, our package is now compiled into `packages/govuk-frontend/dist`.
+
+##### Node.js, Express.js and bundlers
+
+Depending on tools you use to consume GOV.UK Frontend, you may need to make changes to your configuration file or assets paths to replace `node_modules/govuk-frontend` with `node_modules/govuk-frontend/dist`.
+
+This is typically where Node.js v12.19.0+ [`package.json` subpath patterns](https://nodejs.org/docs/latest-v18.x/api/packages.html#subpath-patterns) are not supported.
+
+If your code uses Express.js, updated paths to GOV.UK Frontend assets look like:
+
+```javascript
+app.use('/assets', express.static(path.join(__dirname, '/node_modules/govuk-frontend/dist/govuk/assets')))
+```
+
+Alternatively Node.js can locate `govuk-frontend` for you:
+
+```javascript
+app.use('/assets', express.static(path.join(path.dirname(require.resolve('govuk-frontend')), 'assets')))
+```
+
+##### If you’re using Sass
+
+Replace `govuk-frontend/govuk` with `govuk-frontend/govuk/dist` in [Sass `loadPaths`](https://sass-lang.com/documentation/js-api/interfaces/Options#loadPaths) (previously [`includePaths` in Node Sass](https://sass-lang.com/documentation/js-api/interfaces/LegacyStringOptions#includePaths)).
+
+For example:
+
+```scss
+@import "node_modules/govuk-frontend/dist/govuk/all";
+```
+
+If you’ve [added `node_modules/govuk-frontend` as a Sass import path](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#simplify-sass-import-paths), update it with the `/dist` suffix:
+
+```javascript
+loadPaths: [
+  'node_modules/govuk-frontend/dist'
+]
+```
+
+##### If you’re using Nunjucks
+
+Replace `govuk-frontend/govuk` with `govuk-frontend/govuk/dist` in the search paths passed to [`nunjucks.configure()`](https://mozilla.github.io/nunjucks/api.html#configure).
+
+```javascript
+nunjucks.configure([
+  'node_modules/govuk-frontend/dist'
+])
+```
+
+These changes were made in the following pull requests:
+
+- [#3491: Update Review app to import `govuk-frontend` via local package](https://github.com/alphagov/govuk-frontend/pull/3491)
+- [#3498: Remove built `dist` and `package` from source](https://github.com/alphagov/govuk-frontend/pull/3498)
+
 #### Check that disabled buttons work as expected
 
 The `disabled` attribute on disabled buttons created using our Nunjucks macros no longer includes a value.

Procfile

@@ -1 +1 @@
-web: npm start --workspace app
+web: npm start --workspace packages/govuk-frontend-review

bin/build-release.sh

@@ -3,7 +3,7 @@ set -e
 
 # Check if there are unexpected changes. Changes to CHANGELOG.md and the
 # package.json file are expected as part of the normal release process.
-changes="$(git status --porcelain -- ':!CHANGELOG.md' ':!package/package.json')"
+changes="$(git status --porcelain -- ':!CHANGELOG.md' ':!packages/govuk-frontend/package.json')"
 if [[ -n $changes ]]; then
   echo "⚠ Unexpected changes in your working directory:"
   echo "$changes"
@@ -14,7 +14,7 @@ echo "Starting to build release..."
 echo " "
 echo "This will:"
 echo "- run the test suite"
-echo "- build GOV.UK Frontend into the 'package/' directory"
+echo "- build GOV.UK Frontend into the 'packages/govuk-frontend/dist' directory"
 echo "- build GOV.UK Frontend into the 'dist/' directory"
 echo "- commit all changes and push the branch to remote"
 echo " "
@@ -28,14 +28,14 @@ fi
 
 npm run test
 npm run build:package
-npm run build:dist
+npm run build:release
 
-ALL_PACKAGE_VERSION=$(node -p "require('./package/package.json').version")
+ALL_PACKAGE_VERSION=$(node -p "require('./packages/govuk-frontend/package.json').version")
 TAG="v$ALL_PACKAGE_VERSION"
 CURRENT_BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
 
 if [ $(git tag -l "$TAG") ]; then
-    echo "⚠️ Git tag $TAG already exists. Check you have updated the version in package/package.json correctly."
+    echo "⚠️ Git tag $TAG already exists. Check you have updated the version in packages/govuk-frontend/package.json correctly."
     exit 1;
 else
     git add .

bin/generate-npm-tag.sh

@@ -4,13 +4,13 @@ set -e
 # Get highest tag published on Github
 HIGHEST_PUBLISHED_VERSION=$(git tag --list 2>/dev/null | sort -V | tail -n1 2>/dev/null | sed 's/v//g')
 
-# Extract tag version from ./package/package.json
-CURRENT_VERSION=$(node -p "require('./package/package.json').version")
+# Extract tag version from ./packages/govuk-frontend/package.json
+CURRENT_VERSION=$(node -p "require('./packages/govuk-frontend/package.json').version")
 
 function version() { echo "$@" | awk -F. '{ printf("%d%03d%03d\n", $1,$2,$3); }'; }
 
 if [ $CURRENT_VERSION == $HIGHEST_PUBLISHED_VERSION ]; then
-  echo "⚠️ Git tag $TAG already exists. Check you have updated the version in package/package.json correctly."
+  echo "⚠️ Git tag $TAG already exists. Check you have updated the version in packages/govuk-frontend/package.json correctly."
   exit 1
 elif [ $(version $CURRENT_VERSION) -ge $(version $HIGHEST_PUBLISHED_VERSION) ]; then
   NPM_TAG="latest"

bin/pre-release.sh

@@ -22,24 +22,17 @@ git checkout -b $BRANCH_NAME
 # Build the package as normal
 npm run build:package
 
-# Check if the new built package has anything new to commit
-if [[ -n $(git status --porcelain) ]]; then
-  echo "✍️ Commiting changed package"
-  git add package/
-
-  git commit -m "Release GOV.UK Frontend to '$BRANCH_NAME' for testing"
+echo "✍️ Commiting status"
+git commit --allow-empty -m "Release GOV.UK Frontend to '$BRANCH_NAME' for testing"
 
-  # Create a local branch containing the package directory
-  echo "✨ Filter the branch to only the package/ directory..."
-  git filter-branch --force --subdirectory-filter package
+# Create a local branch containing the packages/govuk-frontend directory
+echo "✨ Filter the branch to only the packages/govuk-frontend/ directory..."
+git filter-branch --force --subdirectory-filter packages/govuk-frontend
 
-  # Force the push of the branch to the remote Github origin
-  git push origin $BRANCH_NAME:$BRANCH_NAME --force
+# Force the push of the branch to the remote Github origin
+git push origin $BRANCH_NAME:$BRANCH_NAME --force
 
-  echo "⚠️ Branch pushed to '$BRANCH_NAME', do not edit this by hand."
-else
-  echo "⚠️ No new changes to the package."
-fi
+echo "⚠️ Branch pushed to '$BRANCH_NAME', do not edit this by hand."
 
 git checkout -
 

bin/publish-release.sh

@@ -48,13 +48,13 @@ fi
 echo "📦  Publishing package..."
 
 # Try publishing
-cd package
+cd packages/govuk-frontend/dist
 [ $NPM_TAG = "latest" ] && npm publish || npm publish --tag $NPM_TAG
 echo "🗒 Package published!"
 cd ..
 
-# Extract tag version from ./package/package.json
-ALL_PACKAGE_VERSION=$(node -p "require('./package/package.json').version")
+# Extract tag version from ./packages/govuk-frontend/package.json
+ALL_PACKAGE_VERSION=$(node -p "require('./packages/govuk-frontend/package.json').version")
 TAG="v$ALL_PACKAGE_VERSION"
 
 if [ $(git tag -l "$TAG") ]; then