Add ES module bundles (all.bundle.mjs) for browsers

Browsers can now `await import()` ES module bundles without having to resolve and download imported child modules (including potentially `node_modules` for polyfills)
alphagov · Jun 20, 2023 · 775110d · 775110d
1 parent 460e584
commit 775110d
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 16 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -205,7 +205,7 @@ jobs:
         run: ${{ matrix.task.run }}
 
   package:
-    name: Export ${{ join(matrix.conditions, ' ') }}, Node.js ${{ matrix.node-version }}
+    name: Export ${{ join(matrix.conditions, ' ') || 'require' }}, Node.js ${{ matrix.node-version }}
     runs-on: ${{ github.event.inputs.runner || 'ubuntu-latest' }}
     needs: [install, build]
 
@@ -217,17 +217,19 @@ jobs:
 
       matrix:
         node-version:
-          - 12.18 # Node.js 12.18 uses package exports with trailing slashes
-          - 12 # But Node.js 12.20+ uses package exports with subpath patterns
-          - 18
+          - 12 # Node.js 12.20+ uses package exports with subpath patterns
+          - 18 # Node.js 17+ cannot use package exports with trailing slashes
 
         conditions:
-          - require
-          - import
+          - [require]
+          - [import]
+          - [browser]
+          - [browser, require]
+          - [browser, import]
 
-        exclude:
-          - conditions: import
-            node-version: 12.18
+        include:
+          - conditions: []
+            node-version: 12.18 # Node.js 12.18 uses package exports with trailing slashes
 
     steps:
       - name: Checkout
@@ -244,11 +246,11 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
-      - name: Export ${{ join(matrix.conditions, ' ') }}, Node.js ${{ matrix.node-version }}
+      - name: Export ${{ join(matrix.conditions, ' ') || 'require' }}, Node.js ${{ matrix.node-version }}
         env:
-          # Node.js conditions override from "require" to "import" etc
+          # Node.js conditions override from "require" (default) to "import" etc
           # https://nodejs.org/api/cli.html#-c-condition---conditionscondition
-          FLAGS: ${{ matrix.conditions != 'require' && format(' --conditions {0}', matrix.conditions) || '' }}
+          FLAGS: ${{ matrix.conditions[0] != null && format(' --conditions {0}', join(matrix.conditions, ' --conditions ')) || '' }}
 
         run: |
           node --eval "console.log(require.resolve('govuk-frontend'))"${{ env.FLAGS }}

diff --git a/packages/govuk-frontend/package.json b/packages/govuk-frontend/package.json
@@ -4,6 +4,7 @@
   "version": "4.6.0",
   "main": "dist/govuk/all.bundle.js",
   "module": "dist/govuk/all.mjs",
+  "browser": "dist/govuk/all.bundle.js",
   "sass": "dist/govuk/all.scss",
   "files": [
     "dist",
@@ -13,6 +14,11 @@
   ],
   "exports": {
     ".": {
+      "browser": {
+        "import": "./dist/govuk/all.bundle.mjs",
+        "require": "./dist/govuk/all.bundle.js",
+        "default": "./dist/govuk/all.bundle.js"
+      },
       "sass": "./dist/govuk/all.scss",
       "import": "./dist/govuk/all.mjs",
       "require": "./dist/govuk/all.js",

diff --git a/packages/govuk-frontend/rollup.publish.config.mjs b/packages/govuk-frontend/rollup.publish.config.mjs
@@ -6,12 +6,14 @@ import { defineConfig } from 'rollup'
 /**
  * Rollup config for npm publish
  *
- * 1. CommonJS modules for Node.js `require()`
+ * 1. CommonJS modules for Node.js or bundler `require()`
  *
- * 2. ECMAScript (ES) modules for browser <script type="module">
+ * 2. ECMAScript (ES) modules for Node.js or bundler `import`
+ *
+ * 3. ECMAScript (ES) module bundles for browser <script type="module">
  *    or using `import` for modern browsers and Node.js scripts
  *
- * 3. Universal Module Definition (UMD) bundle for browser <script>
+ * 4. Universal Module Definition (UMD) bundle for browser <script>
  *    `window` globals and compatibility with CommonJS and AMD `require()`
  */
 export default defineConfig(({ i: input }) => ({
@@ -33,6 +35,10 @@ export default defineConfig(({ i: input }) => ({
       format: 'es',
       preserveModules: true
     },
+    {
+      format: 'es',
+      preserveModules: false
+    },
     {
       format: 'umd',
       preserveModules: false,

diff --git a/packages/govuk-frontend/tasks/build/package.test.mjs b/packages/govuk-frontend/tasks/build/package.test.mjs
@@ -80,7 +80,11 @@ describe('packages/govuk-frontend/dist/', () => {
 
         // UMD bundles for compatibility (e.g. Rails Asset Pipeline)
         join(requirePath, `${name}.bundle.js`),
-        join(requirePath, `${name}.bundle.js.map`) // with source map
+        join(requirePath, `${name}.bundle.js.map`), // with source map
+
+        // ES module bundles for browsers
+        join(requirePath, `${name}.bundle.mjs`),
+        join(requirePath, `${name}.bundle.mjs.map`) // with source map
       ]))
 
       // Add Autoprefixer prefixes to all source '*.scss' files