From 907c8ae405104a174c0a8a5c3f70a8316fd7cb3f Mon Sep 17 00:00:00 2001 From: Caspar MacRae Date: Mon, 14 Mar 2022 19:49:36 +0000 Subject: [PATCH 1/7] Docs: dependencies mgmt for vanilla ESM in browser Doc change for https://github.com/twbs/bootstrap/issues/31944 --- .../docs/5.1/getting-started/javascript.md | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/site/content/docs/5.1/getting-started/javascript.md b/site/content/docs/5.1/getting-started/javascript.md index 8ee4289211b8..2652d1675a7f 100644 --- a/site/content/docs/5.1/getting-started/javascript.md +++ b/site/content/docs/5.1/getting-started/javascript.md @@ -26,9 +26,43 @@ We provide a version of Bootstrap built as `ESM` (`bootstrap.esm.js` and `bootst ``` {{< callout warning >}} -## Incompatible plugins +## Dependencies for vanilla ESM in the browser requires an `importmap` + +In order to support build tools, NPM dependencies, etc - external dependencies such as PopperJs are `import`ed with their NPM package name (e.g. `@popperjs/core`), to make this work in the browser you need to define an `importmap` which resolves arbitrary names to fully-qualified or relative URIs. + +If your [targeted browsers](https://caniuse.com/?search=importmap) do not support `importmap` then you will need to use the [es-module-shims](https://github.com/guybedford/es-module-shims) library. For example: + +```html + + + + + + + Hello, modularity! + + +

Hello, modularity!

+ + + + + + + +``` -Due to browser limitations, some of our plugins, namely Dropdown, Tooltip and Popover plugins, cannot be used in a ` - - + + + + }}" rel="stylesheet" integrity="{{< param "cdn.css_hash" >}}" crossorigin="anonymous"> + Hello, modularity! + + +

Hello, modularity!

+ + + + + ``` From c7974cac9527c6f43bacd64ad4f2b677b68ec4ae Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Tue, 15 Mar 2022 10:09:01 +0200 Subject: [PATCH 3/7] Update javascript.md --- site/content/docs/5.1/getting-started/javascript.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/docs/5.1/getting-started/javascript.md b/site/content/docs/5.1/getting-started/javascript.md index 18d34d589341..d73cea93ea83 100644 --- a/site/content/docs/5.1/getting-started/javascript.md +++ b/site/content/docs/5.1/getting-started/javascript.md @@ -43,7 +43,7 @@ If your [targeted browsers](https://caniuse.com/?search=importmap) do not suppor

Hello, modularity!

- + From 8d42ec0278811552ed7756c892d94b47d1b80161 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Tue, 15 Mar 2022 10:09:33 +0200 Subject: [PATCH 4/7] Update .cspell.json --- .cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.cspell.json b/.cspell.json index 8562645cfe90..25b3e307a4f7 100644 --- a/.cspell.json +++ b/.cspell.json @@ -48,6 +48,7 @@ "Hoverable", "hreflang", "hstack", + "importmap", "jsdelivr", "Jumpstart", "keyframes", From 0f03b838432c9ec05a1620e82220864ba5758ac5 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Tue, 15 Mar 2022 10:13:27 +0200 Subject: [PATCH 5/7] Update javascript.md --- site/content/docs/5.1/getting-started/javascript.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/docs/5.1/getting-started/javascript.md b/site/content/docs/5.1/getting-started/javascript.md index d73cea93ea83..38cf2c6777ec 100644 --- a/site/content/docs/5.1/getting-started/javascript.md +++ b/site/content/docs/5.1/getting-started/javascript.md @@ -50,12 +50,12 @@ If your [targeted browsers](https://caniuse.com/?search=importmap) do not suppor { "imports": { "@popperjs/core": "{{< param "cdn.popper" >}}", - "@twbs/bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@{{< param "current_version" >}}/dist/js/bootstrap.esm.min.js" + "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@{{< param "current_version" >}}/dist/js/bootstrap.esm.min.js" } } From 739ebd9b21dfb0542523ba7a7be22e8b8245e45d Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Tue, 15 Mar 2022 10:21:42 +0200 Subject: [PATCH 6/7] Update javascript.md --- site/content/docs/5.1/getting-started/javascript.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/content/docs/5.1/getting-started/javascript.md b/site/content/docs/5.1/getting-started/javascript.md index 38cf2c6777ec..1fd8590491eb 100644 --- a/site/content/docs/5.1/getting-started/javascript.md +++ b/site/content/docs/5.1/getting-started/javascript.md @@ -26,7 +26,7 @@ We provide a version of Bootstrap built as `ESM` (`bootstrap.esm.js` and `bootst ``` {{< callout warning >}} -## Dependencies for vanilla ESM in the browser requires an `importmap` +## Dependencies for vanilla ESM in the browser require an `importmap` In order to support build tools, npm dependencies - external dependencies such as Popper are `import`ed with their npm package name (e.g. `@popperjs/core`), to make this work in the browser you need to define an `importmap` which resolves arbitrary names to fully-qualified or relative URIs. @@ -45,7 +45,7 @@ If your [targeted browsers](https://caniuse.com/?search=importmap) do not suppor

Hello, modularity!

- + ``` -{{< callout warning >}} -## Dependencies for vanilla ESM in the browser require an `importmap` +Compared to JS bundlers, using ESM in the browser requires you to use the full path and filename instead of the module name. That's why we use `'bootstrap.esm.min.js'` instead of `'bootstrap'` above. This is further complicated by our Popper dependency, which imports Popper like so: + +```js +import * as Popper from "@popperjs/core" +``` + +If you try this as-is, you'll see an error in the console like the following: -In order to support build tools, npm dependencies - external dependencies such as Popper are `import`ed with their npm package name (e.g. `@popperjs/core`), to make this work in the browser you need to define an `importmap` which resolves arbitrary names to fully-qualified or relative URIs. +```text +Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../". +``` -If your [targeted browsers](https://caniuse.com/?search=importmap) do not support `importmap` then you will need to use the [es-module-shims](https://github.com/guybedford/es-module-shims) library. For example: +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 @@ -43,7 +54,7 @@ If your [targeted browsers](https://caniuse.com/?search=importmap) do not suppor

Hello, modularity!

- + -