Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve ES module and alternative format documentation #404

Merged
merged 6 commits into from
Dec 8, 2023
Merged
52 changes: 43 additions & 9 deletions source/importing-css-assets-and-javascript/index.html.md.erb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down