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.

Sign up for GitHub

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

notes about lazy and module loading for :browser and :esm targets #93

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

notes about lazy and module loading for :browser and :esm targets #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 26 additions & 2 deletions docs/UsersGuide.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3802,6 +3802,18 @@ <h4 id="_loading_code_dynamically"><a class="anchor" href="#_loading_code_dynami
<div class="paragraph">
<p>There are a couple ways of loading code dynamically. <code>shadow.lazy</code> is the most convenient and easiest.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<code>shadow.lazy</code> is only intended for use with the <code>:browser</code> target. If you are targeting <code>:esm</code>, consider using <code>shadow.esm/dynamic-import</code>.
</td>
</tr>
</table>
</div>
<div class="sect4">
<h5 id="_using_shadow_lazy"><a class="anchor" href="#_using_shadow_lazy"></a><a class="link" href="#_using_shadow_lazy">Using shadow.lazy</a></h5>
<div class="paragraph">
Expand Down Expand Up @@ -4774,7 +4786,19 @@ <h3 id="_dynamic_module_import"><a class="anchor" href="#_dynamic_module_import"
</div>
</div>
<div class="paragraph">
<p>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 <code>:modules</code> dynamically this way too.</p>
<p>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 <code>:modules</code> dynamically this way too, referencing them by url. It is not currently possible to load your modules by name with <code>dynamic-import</code>.</p>
</div>
<div class="paragraph">
<p><code>dynamic-import</code> is only intended for use with the <code>:esm</code> target. The purpose of this helper is to work around an issue with the Closure compiler - we cannot directly call <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import"><code>import</code></a> from code processed by Closure. <code>dynamic-import</code> calls a function that wraps <code>import</code> in a way that Closure cannot interfere with. If you are using a different target such as <code>:browser</code>, you can make <code>shadow.esm/dynamic-import</code> work by adding to your build config:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="clojure">{<span class="symbol">:builds</span>
{<span class="symbol">:build-id</span>
{<span class="symbol">:modules</span>
{<span class="symbol">:module-id</span>
{<span class="symbol">:prepend</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">window.shadow_esm_import = function(x) { return import(x); };</span><span class="delimiter">&quot;</span></span>}}}}}</code></pre>
</div>
</div>
</div>
<div class="sect2">
Expand Down Expand Up @@ -7618,7 +7642,7 @@ <h3 id="_patching_libraries"><a class="anchor" href="#_patching_libraries"></a><
<div id="footer">
<div id="footer-text">
Version 1.0<br>
Last updated 2022-08-05 09:27:21 CEST
Last updated 2023-07-21 20:06:01 UTC
</div>
</div>
</body>
Expand Down
2 changes: 2 additions & 0 deletions docs/target-browser.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
11 changes: 10 additions & 1 deletion docs/target-esm.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down