Merge pull request #404 from alphagov/javascript-flavours

Improve ES module and alternative format documentation

source/importing-css-assets-and-javascript/index.html.md.erb

@@ -176,10 +176,10 @@ This snippet adds the `.govuk-frontend-supported` class in supported browsers:
 
 You should check [if our snippet is blocked by a Content Security Policy](#if-our-inline-javascript-snippet-is-blocked-by-a-content-security-policy).
 
-To import the JavaScript from GOV.UK Frontend, you can either:
+Next, to import the JavaScript from GOV.UK Frontend, you can either:
 
-- add GOV.UK Frontend's JavaScript file to your HTML
-- import the JavaScript using a bundler like [Webpack](https://webpack.js.org/)
+- add the JavaScript file to your HTML
+- import the JavaScript into your own JavaScript file using a bundler
 
 ### Add the JavaScript file to your HTML
 
@@ -208,37 +208,71 @@ Read about how we log [JavaScript errors in the browser console](../configure-co
 
 ### Import JavaScript using a bundler
 
-If you decide to import using a bundler, we recommend you use `import` to only import the JavaScript for components you're using in your service. For example:
+If you decide to import using a bundler like [Rollup](https://rollupjs.org/) or [webpack](https://webpack.js.org/), the bundled JavaScript files must be added using `<script type="module">` in your HTML:
+
+```html
+<script type="module" src="<YOUR-JAVASCRIPTS-FOLDER>/app-bundle.min.js"></script>
+```
+
+We encourage the use of ECMAScript (ES) modules, but you should check your bundler does not unnecessarily downgrade modern JavaScript for unsupported browsers.
+
+If your service cannot use ES modules, read about [alternative module formats](#import-javascript-using-alternative-module-formats) below.
+
+#### Import individual components
+
+If you want to improve how quickly your service’s pages load in browsers, you can import only the JavaScript components you need.
 
 ```javascript
 import { SkipLink, Radios } from 'govuk-frontend'
 
 const $skipLink = document.querySelector('[data-module="govuk-skip-link"]')
 new SkipLink($skipLink)
+```
+
+When using a component more than once, the same `import` can be initialised again:
+
+```javascript
+import { Radios } from 'govuk-frontend'
 
 const $radios = document.querySelectorAll('[data-module="govuk-radios]')
 $radios.forEach(($radio) => {
   new Radios($radio)
 })
 ```
 
+#### Import and initialise all components using the initAll function
+
 If you need to import all of GOV.UK Frontend's components, then run the `initAll` function to initialise them:
 
 ```javascript
 import { initAll } from 'govuk-frontend'
 initAll()
 ```
 
-If you're using a bundler that uses CommonJS like [Browserify](http://browserify.org/), you should use `require`:
+### Import JavaScript using alternative module formats
+
+#### Universal Module Definition (UMD)
+
+For projects that cannot import ECMAScript (ES) modules, we also publish pre-built Universal Module Definition (UMD) bundles to support the following formats:
+
+* Asynchronous Module Definition (AMD)
+* Browser `window.GOVUKFrontend` global
+* CommonJS
+
+Bundlers like [Browserify](http://browserify.org/) can use `require()` to import UMD bundles:
 
 ```javascript
-const { initAll } = require('govuk-frontend')
-initAll()
+const { Accordion } = require('govuk-frontend')
 ```
 
-### UMD and `window` globals support
+Rails Assets Pipeline or Sprockets can use `require` directives to import UMD bundles:
+
+```javascript
+// = require govuk/components/accordion/accordion.bundle.js
+const { Accordion } = window.GOVUKFrontend;
+```
 
-We encourage the use of ECMAScript (ES) modules. For projects that cannot use them and require UMD or `window` globals, our package contains `.bundle.js` files.
+**Note:** Using pre-built bundles instead of ECMAScript (ES) modules will output considerably larger JavaScript files. You can read more about [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) on the MDN website.
 
 ### If our inline JavaScript snippet is blocked by a Content Security Policy