Default to ES modules with single Rollup config

[colinrotherham]

This PR consolidates all govuk-frontend npm package JavaScript into the govuk directory

We use Rollup to build JavaScript into the following formats + extensions:

• ECMAScript (ES) modules as *.mjs
• ECMAScript (ES) module bundles as *.bundle.mjs
• Universal Module Definition (UMD) bundles as *.bundle.js

But like we do for our GitHub release zip files also add a "ready to go" minified bundle for:

• ECMAScript (ES) module bundle minified as govuk-frontend.min.js

CommonJS compatibility

We've felt the pain of "ESM only" packages recently and know that CommonJS compatibility is important for both Node.js require('govuk-frontend') package resolution and for test runners that don't support ES modules yet

By dropping CommonJS and going "ESM only" we'd hit issues such as:

1. Jest ECMAScript modules support needing --experimental-vm-modules
2. Mocha current limitations like --watch mode only working with CommonJS

Although more complex workarounds like Babel compiling ES modules to CommonJS can work instead

Legacy bundlers

Some bundlers like Browserify support require('govuk-frontend') but may need AMD not CommonJS format. Similarly the unpkg CDN falls back to expect a UMD bundle in package.json "main"

Package layout

dist
└── govuk
    ├── govuk-frontend.min.js         # ECMAScript (ES) module bundle, minified
    │
    ├── all.mjs                       # ECMAScript (ES) module
    ├── all.bundle.mjs                # ECMAScript (ES) module bundle
    ├── all.bundle.js                 # Universal Module Definition (UMD) bundle
    │
    └── components
        ├── accordion
        │   ├── accordion.mjs         # ECMAScript (ES) module
        │   ├── accordion.bundle.mjs  # ECMAScript (ES) module bundle
        │   └── accordion.bundle.js   # Universal Module Definition (UMD) bundle
        │
        └── button
            ├── button.mjs            # ECMAScript (ES) module
            ├── button.bundle.mjs     # ECMAScript (ES) module bundle
            └── button.bundle.js      # Universal Module Definition (UMD) bundle

Script includes

But by adding "ready to go" bundles all.bundle.js (UMD) and all.bundle.mjs (ES module) we maintain non-bundler compatibility even when importing JavaScript directly (see README.md)

✅ Rails Asset Pipeline using //= require to concatenate UMD all.bundle.js
✅ Browsers using dynamic await import() to load ES module all.bundle.mjs
✅ Browsers using <script type="module"> to load ES module all.bundle.mjs

<script src="/javascripts/all.bundle.js"></script>
<script>window.GOVUKFrontend.initAll()</script>

<script type="module">
  import { initAll } from '/javascripts/all.bundle.mjs'
  initAll()
</script>

Note: Only govuk-frontend.min.js is minified, unlike other bundles

Window globals

What do we do about UMD-only window globals like window.GOVUKFrontend.Accordion?

Regarding window globals we'll continue to support UMD bundles in v5 but will deprecate them in a future release

[romaricpascal]

That looks promising and super helpful for discussing #3721.

Regarding the output, so we're clear on what our options are, does that mean we have complete flexibility on:

• the format, between esm, cjs, umd and iife via the format option
• whether the imported modules are bundled in the resulting file or left as import statements via the preserveModules option

I also like that we could move to a unique tree thanks to the ./* path in the exports (more related to #3482 that part).

[colinrotherham]

Thanks @romaricpascal

Yeah it's primarily to address this "modules versus bundles" thread which caught us out

Historically we've bundled every JavaScript file separately into UMD, but now we can pick any module format and even CommonJS bundlers should be able to do tree-shaking

[36degrees]

Just remove the version number, leaving govuk-frontend.min.js?

With the namespace directory maaaybe govuk/govuk-frontend.min.js govuk/frontend.min.js??

I reckon govuk-frontend.min.js just to be really clear, if the file is copied or routed without keeping the directory name intact it'd still be clear what was being imported if you see it in a script tag.

I don't actually remember what we said we wanted to do with all of the all.* files…

We just had too many of them! Narrowed down a lot since then:

all.cjs
all.mjs
all.bundle.js
all.bundle.mjs
all.bundle.min.js
all.bundle.min.mjs → govuk-frontend.min.js

Would it be more idiomatic to go with index.*? Otherwise I think we're good, does seem a lot more manageable with the other changes.

[colinrotherham]

Would it be more idiomatic to go with index.*? Otherwise I think we're good, does seem a lot more manageable with the other changes.

@36degrees Yeah let's leave it for another PR

Must have been intentional at some point and matches Sass all.scss too

[36degrees]

Thanks for your patience as we worked through all of this @colinrotherham 🙌🏻

[colinrotherham]

Ready for review again Beat me to it thanks @36degrees

Last push removed the version suffix from the "browser ready" minified bundle:

import { initAll } from '/javascripts/govuk-frontend.min.js'

I've updated our decision document to reflect this:

• Add decision record about JavaScript file names and formats govuk-design-system-architecture#28

[colinrotherham]

We'll update our README.md Importing JavaScript advice in another PR:

You can include Javascript for all components either by copying the all.bundle.js from node_modules/govuk-frontend/dist/govuk/ into your application or referencing the file directly:

<script type="module" src="<path-to-govuk-frontend-all-file>/all.bundle.js"></script>

☝️ It's still using the UMD + window globals approach but via <script type="module">