From d251afd759cddbb281faa86a6939ce1dec11ee48 Mon Sep 17 00:00:00 2001 From: Tom Connors Date: Fri, 21 Jul 2023 16:28:29 -0400 Subject: [PATCH] notes about lazy and module loading for :browser and :esm targets --- docs/UsersGuide.html | 28 ++++++++++++++++++++++++++-- docs/target-browser.adoc | 2 ++ docs/target-esm.adoc | 11 ++++++++++- 3 files changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/UsersGuide.html b/docs/UsersGuide.html index 3c01e08..b64ad65 100644 --- a/docs/UsersGuide.html +++ b/docs/UsersGuide.html @@ -3802,6 +3802,18 @@

There are a couple ways of loading code dynamically. shadow.lazy is the most convenient and easiest.

+
+ + + + + +
+
Note
+		 +shadow.lazy is only intended for use with the :browser target. If you are targeting :esm, consider using shadow.esm/dynamic-import. +
+
Using shadow.lazy
@@ -4774,7 +4786,19 @@

-

This would load an external ESM module dynamically at runtime without it ever being part of the build. You can of course also load your own :modules dynamically this way too.

+

This would load an external ESM module dynamically at runtime without it ever being part of the build. You can of course also load your own :modules dynamically this way too, referencing them by url. It is not currently possible to load your modules by name with dynamic-import.

+
+
+

dynamic-import is only intended for use with the :esm target. The purpose of this helper is to work around an issue with the Closure compiler - we cannot directly call import from code processed by Closure. dynamic-import calls a function that wraps import in a way that Closure cannot interfere with. If you are using a different target such as :browser, you can make shadow.esm/dynamic-import work by adding to your build config:

+
+
+
+
{:builds
+ {:build-id
+  {:modules
+   {:module-id
+    {:prepend "window.shadow_esm_import = function(x) { return import(x); };"}}}}}
+
@@ -7618,7 +7642,7 @@

< diff --git a/docs/target-browser.adoc b/docs/target-browser.adoc index 1429292..2a489db 100644 --- a/docs/target-browser.adoc +++ b/docs/target-browser.adoc @@ -151,6 +151,8 @@ The more dynamic your website gets, the more dynamic your requirements may get. There are a couple ways of loading code dynamically. `shadow.lazy` is the most convenient and easiest. +NOTE: `shadow.lazy` is only intended for use with the `:browser` target. If you are targeting `:esm`, consider using `shadow.esm/dynamic-import`. + ==== Using shadow.lazy As https://clojureverse.org/t/shadow-lazy-convenience-wrapper-for-shadow-loader-cljs-loader/3841[announced here] shadow-cljs provides a convenience method for referring to potentially lazy loaded code. diff --git a/docs/target-esm.adoc b/docs/target-esm.adoc index ea064b0..9aee553 100644 --- a/docs/target-esm.adoc +++ b/docs/target-esm.adoc @@ -193,8 +193,17 @@ Modules can also be loaded dynamically at runtime via the provided `shadow.esm/d (js/console.log "loaded module" mod))) ``` -This would load an external ESM module dynamically at runtime without it ever being part of the build. You can of course also load your own `:modules` dynamically this way too. +This would load an external ESM module dynamically at runtime without it ever being part of the build. You can of course also load your own `:modules` dynamically this way too, referencing them by url. It is not currently possible to load your modules by name with `dynamic-import`. +`dynamic-import` is only intended for use with the `:esm` target. The purpose of this helper is to work around an issue with the Closure compiler - we cannot directly call https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import[`import`] from code processed by Closure. `dynamic-import` calls a function that wraps `import` in a way that Closure cannot interfere with. If you are using a different target such as `:browser`, you can make `shadow.esm/dynamic-import` work by adding to your build config: + +```clojure +{:builds + {:build-id + {:modules + {:module-id + {:prepend "window.shadow_esm_import = function(x) { return import(x); };"}}}}} +``` == Third Party Tool Integration