Resolve `pkg:` URLs from `dist/govuk` and update the review app by romaricpascal · Pull Request #6839 · alphagov/govuk-frontend

romaricpascal · 2026-03-12T15:37:30Z

When using Sass, resolve any string after pkg:govuk-frontend from dist/govuk rather than the root of the package. This allows to reduce the length of pkg: URLs:

# Previously
@use "pkg:govuk-frontend/dist/govuk/components/button"
# Now
@use "pkg:govuk-frontend/components/button"

As a way to confirm things are working OK the PR also:

updates the review app to consume GOV.UK Frontend using pkg: URLs
add a test using a JavaScript component importing the component's mjs file (to check JS exports still work as intended)

Best reviewed commit by commit.

Fixes #6822

github-actions · 2026-03-12T15:41:59Z

📋 Stats

No changes to any distributed file sizes!

Action run for 661aeb3

romaricpascal · 2026-03-12T15:42:08Z

packages/govuk-frontend/package.json

+    "./package.json": "./package.json",
+    "./*": {
+      "sass": "./dist/govuk/*",
+      "default": "./*"


note Judging by the content of GOV.UK Frontend's package, I think we could also update this to ./dist/govuk/* to help people import JavaScript more easily.

I believe the change would not be breaking as README.md is. the only other file in the package outside of dist, govuk-prototype-kit.config.json, and package.json. We could just add an entry for it in the list of exports if we're worried about this one.

All in all, it's a separate matter than Sass module resolution, so best tackled in its own PR as we'd want some tests specific to JavaScript around it.

Agree, this sounds like something to do in a follow up PR 👍🏻 It might also need some docs changes – think all of our JS examples at the minute import via all.mjs.

romaricpascal · 2026-03-12T17:56:32Z

tsconfig.base.json

      "@govuk-frontend/tasks": ["./shared/tasks/index.mjs"],
-      "govuk-frontend": ["./packages/govuk-frontend/src/govuk/all.mjs"]
+      "govuk-frontend": ["./packages/govuk-frontend/src/govuk/all.mjs"],
+      "govuk-frontend/dist/govuk/components/button/button.mjs": [


note This one probably needs some explaining.

The addition of a file importing the component file individually ends up making TypeScript process govuk-frontend/dist/govuk/components/button/button.mjs and the files it imports.

However... we do not ship types in GOV.UK Frontend, so TypeScript throws a bunch of errors when processing compiled files from GOV.UK Frontend.

Instead, we need to do like for govuk-frontend right above and point TypeScript to src.

Suggestion: Would it make sense to add a tsconfig.json to tests or even tests/bundler-integrations that extends the base config and handles this there, so it's closer to the code that needs it?

Also, it looks like tsconfig.json allows comments 🤯 (tsc --init even adds some to the file) – so we could use that to document this inline.

I could try for govuk-frontend/dist/govuk/components/button/button.mjs, however govuk-frontend needs to be a little more central as it's also used in the review app. Probably best to add a comment in there, that's a good shout.

36degrees · 2026-03-13T16:36:33Z

tsconfig.base.json

      "@govuk-frontend/tasks": ["./shared/tasks/index.mjs"],
-      "govuk-frontend": ["./packages/govuk-frontend/src/govuk/all.mjs"]
+      "govuk-frontend": ["./packages/govuk-frontend/src/govuk/all.mjs"],
+      "govuk-frontend/dist/govuk/components/button/button.mjs": [


Suggestion: Would it make sense to add a tsconfig.json to tests or even tests/bundler-integrations that extends the base config and handles this there, so it's closer to the code that needs it?

Also, it looks like tsconfig.json allows comments 🤯 (tsc --init even adds some to the file) – so we could use that to document this inline.

36degrees · 2026-03-13T16:37:55Z

packages/govuk-frontend/package.json

+    "./package.json": "./package.json",
+    "./*": {
+      "sass": "./dist/govuk/*",
+      "default": "./*"


Agree, this sounds like something to do in a follow up PR 👍🏻 It might also need some docs changes – think all of our JS examples at the minute import via all.mjs.

36degrees · 2026-03-13T16:38:35Z

shared/tasks/styles.mjs

-        join(basePath, 'node_modules'),
-        join(paths.root, 'node_modules')
-      ],
+      importers: [new NodePackageImporter()],


Praise: Neat! 🧹

36degrees · 2026-03-13T16:43:07Z

tests/sass-tests/pkg-urls.integration.test.mjs

+
+      const { css } = await compileStringAsync(sass, sassConfig)
+
+      expect(css).toBe(cssWithPkg)


Nit: This feels backwards to me – I'd expect us to check that the Sass compiled using pkg: matches the Sass compiled using the more definite file path.

Appreciate it's functionally identical, but if they were different the diff would be the inverse of what the description for the describe block implies, I think?

Similarly I'd expect the thing compiled outside of the test to be the fileUrl as the 'control' for the test.

Sounds fair, I'll tidy the order on Monday 😊

When using Sass, resolve any string after `pkg:govuk-frontend` from `dist/govuk` rather than the root of the package. This allows to reduce the length of `pkg:` URLs. The `./*` entry of `exports` has been moved to the bottom of the list as Node recommends ordering from more to least specific: > Within the "exports" object, key order is significant. During condition matching, earlier entries have higher priority and take precedence over later entries. The general rule is that conditions should be from most specific to least specific in object order. > - <https://nodejs.org/api/packages.html#self-referencing-a-package-using-its-name> This allows users to still access files explicitely using `dist/govuk` should they wish to, making this a non-breaking change if they were doing: `@use "pkg:govuk-frontend/dist/govuk"`. (In practice, it was also working with `./*` at the top of the list, I _think_ because no file matched `dist/govuk/dist/govuk` in the package so Node moved on to the next entry. But better safe than sorry.)

domoscargin

Looks grand!

tsconfig.base.json

Ensures importing individual component files still resolves properly. Because GOV.UK Frontend does not provide type definitions in the built files, we need to do a similar mapping as for `govuk-frontend` and point to `src` rather than `dist`.

Upgrade styles compilation to use Sass' `NodePackageImporter` rather than a custom `loadPath`. This means we can now use `pkg:govuk-frontend` in the review app, which has been updated.

romaricpascal commented Mar 12, 2026

View reviewed changes

govuk-design-system-ci temporarily deployed to govuk-frontend-pr-6839 March 12, 2026 15:43 Inactive

romaricpascal force-pushed the sass-pkg-urls branch from 6f12b7a to fb364a6 Compare March 12, 2026 15:59

govuk-design-system-ci temporarily deployed to govuk-frontend-pr-6839 March 12, 2026 15:59 Inactive

romaricpascal force-pushed the sass-pkg-urls branch from fb364a6 to e821358 Compare March 12, 2026 17:31

govuk-design-system-ci temporarily deployed to govuk-frontend-pr-6839 March 12, 2026 17:31 Inactive

romaricpascal force-pushed the sass-pkg-urls branch from e821358 to baf6631 Compare March 12, 2026 17:45

govuk-design-system-ci temporarily deployed to govuk-frontend-pr-6839 March 12, 2026 17:45 Inactive

romaricpascal commented Mar 12, 2026

View reviewed changes

romaricpascal marked this pull request as ready for review March 12, 2026 17:56

36degrees reviewed Mar 13, 2026

View reviewed changes

romaricpascal force-pushed the sass-pkg-urls branch from baf6631 to 1483246 Compare March 16, 2026 09:20

govuk-design-system-ci temporarily deployed to govuk-frontend-pr-6839 March 16, 2026 09:20 Inactive

romaricpascal force-pushed the sass-pkg-urls branch from 1483246 to 2f3bcfc Compare March 16, 2026 10:31

govuk-design-system-ci temporarily deployed to govuk-frontend-pr-6839 March 16, 2026 10:31 Inactive

romaricpascal requested a review from a team March 16, 2026 10:36

domoscargin approved these changes Mar 16, 2026

View reviewed changes

tsconfig.base.json Outdated Show resolved Hide resolved

romaricpascal added 2 commits March 16, 2026 10:48

Use pkg: URLs in the review app

661aeb3

Upgrade styles compilation to use Sass' `NodePackageImporter` rather than a custom `loadPath`. This means we can now use `pkg:govuk-frontend` in the review app, which has been updated.

romaricpascal force-pushed the sass-pkg-urls branch from 2f3bcfc to 661aeb3 Compare March 16, 2026 10:48

govuk-design-system-ci deployed to govuk-frontend-pr-6839 March 16, 2026 10:49 View deployment

romaricpascal requested a review from domoscargin March 16, 2026 11:04


		const { css } = await compileStringAsync(sass, sassConfig)

		expect(css).toBe(cssWithPkg)

Conversation

romaricpascal commented Mar 12, 2026

Uh oh!

github-actions bot commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Stats

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

domoscargin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Mar 12, 2026 •

edited

Loading