mirror of https://github.com/twbs/bootstrap.git
Add docs info for using JS w/ ESM shim (#36414)
* Docs: dependencies mgmt for vanilla ESM in browser Doc change for https://github.com/twbs/bootstrap/issues/31944 * Update javascript.md * Update javascript.md * Update .cspell.json * Update javascript.md * Update javascript.md * rewrite * Add link * edit * eslint-skip Co-authored-by: Caspar MacRae <earcam@gmail.com> Co-authored-by: XhmikosR <xhmikosr@gmail.com>
This commit is contained in:
Mark Otto
GitHub
parent
dea14df8ca
commit
461596e5ea
|
|
@ -50,6 +50,7 @@
|
||||||
"Hoverable",
|
"Hoverable",
|
||||||
"hreflang",
|
"hreflang",
|
||||||
"hstack",
|
"hstack",
|
||||||
|
"importmap",
|
||||||
"jsdelivr",
|
"jsdelivr",
|
||||||
"Jumpstart",
|
"Jumpstart",
|
||||||
"keyframes",
|
"keyframes",
|
||||||
|
|
|
||||||
|
|
@ -24,7 +24,11 @@ A better alternative for those using this type of frameworks is to use a framewo
|
||||||
|
|
||||||
## Using Bootstrap as a module
|
## Using Bootstrap as a module
|
||||||
|
|
||||||
We provide a version of Bootstrap built as `ESM` (`bootstrap.esm.js` and `bootstrap.esm.min.js`) which allows you to use Bootstrap as a module in your browser, if your [targeted browsers support it](https://caniuse.com/es6-module).
|
{{< callout >}}
|
||||||
|
**Try it yourself!** Download the source code and working demo for using Bootstrap as an ES module from the [twbs/examples repository](https://github.com/twbs/examples/tree/main/sass-js-esm). You can also [open the example in StackBlitz](https://stackblitz.com/github/twbs/examples/tree/main/sass-js-esm?file=index.html).
|
||||||
|
{{< /callout >}}
|
||||||
|
|
||||||
|
We provide a version of Bootstrap built as `ESM` (`bootstrap.esm.js` and `bootstrap.esm.min.js`) which allows you to use Bootstrap as a module in the browser, if your [targeted browsers support it](https://caniuse.com/es6-module).
|
||||||
|
|
||||||
```html
|
```html
|
||||||
<script type="module">
|
<script type="module">
|
||||||
|
|
@ -35,11 +39,51 @@ We provide a version of Bootstrap built as `ESM` (`bootstrap.esm.js` and `bootst
|
||||||
</script>
|
</script>
|
||||||
```
|
```
|
||||||
|
|
||||||
{{< callout warning >}}
|
Compared to JS bundlers, using ESM in the browser requires you to use the full path and filename instead of the module name. [Read more about JS modules in the browser.](https://v8.dev/features/modules#specifiers) That's why we use `'bootstrap.esm.min.js'` instead of `'bootstrap'` above. However, this is further complicated by our Popper dependency, which imports Popper into our JavaScript like so:
|
||||||
## Incompatible plugins
|
|
||||||
|
|
||||||
Due to browser limitations, some of our plugins, namely Dropdown, Tooltip and Popover plugins, cannot be used in a `<script>` tag with `module` type because they depend on Popper. For more information about the issue see [here](https://v8.dev/features/modules#specifiers).
|
<!-- eslint-skip -->
|
||||||
{{< /callout >}}
|
```js
|
||||||
|
import * as Popper from "@popperjs/core"
|
||||||
|
```
|
||||||
|
|
||||||
|
If you try this as-is, you'll see an error in the console like the following:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".
|
||||||
|
```
|
||||||
|
|
||||||
|
To fix this, you can use an `importmap` to resolve the arbitrary module names to complete paths. If your [targeted browsers](https://caniuse.com/?search=importmap) do not support `importmap`, you'll need to use the [es-module-shims](https://github.com/guybedford/es-module-shims) project. Here's how it works for Bootstrap and Popper:
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!doctype html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
|
<link href="{{< param "cdn.css" >}}" rel="stylesheet" integrity="{{< param "cdn.css_hash" >}}" crossorigin="anonymous">
|
||||||
|
<title>Hello, modularity!</title>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h1>Hello, modularity!</h1>
|
||||||
|
<button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>
|
||||||
|
|
||||||
|
<script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
|
||||||
|
<script type="importmap">
|
||||||
|
{
|
||||||
|
"imports": {
|
||||||
|
"@popperjs/core": "{{< param "cdn.popper" >}}",
|
||||||
|
"bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@{{< param "current_version" >}}/dist/js/bootstrap.esm.min.js"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
<script type="module">
|
||||||
|
import * as bootstrap from 'bootstrap'
|
||||||
|
|
||||||
|
new bootstrap.Popover(document.getElementById('popoverButton'))
|
||||||
|
</script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
```
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue