Skip to content

Commit

Permalink
deploy: 3a41c4a
Browse files Browse the repository at this point in the history
  • Loading branch information
@ctron
ctron committed Mar 8, 2024
1 parent 850640d commit 5879608
Show file tree
Hide file tree
Showing 8 changed files with 384 additions and 95 deletions.
260 changes: 260 additions & 0 deletions advanced/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
<!DOCTYPE html>
<html lang="en">

<head>
<meta charset="UTF-8">
<title>Advanced | Trunk | Build, bundle &amp; ship your Rust WASM application to the web </title>
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<style>
:root {
/* Primary theme color */
--primary-color: #FED43F;
/* Primary theme text color */
--primary-text-color: #543631;
/* Primary theme link color */
--primary-link-color: #F9BB2D;
/* Secondary color: the background body color */
--secondary-color: #fcfaf6;
--secondary-text-color: #303030;
/* Highlight text color of table of content */
--toc-highlight-text-color: #d46e13;
}
</style>
<link href="https://fonts.googleapis.com/css?family=Alfa+Slab+One&display=swap" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Fira+Sans:400,500,600&display=swap" rel="stylesheet">
<link rel="stylesheet" href="/normalize.css">
<link rel="stylesheet" href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;juice.css">

<link rel="icon" type="image/svg+xml" href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;rustacean-flat-happy.svg">
<link rel="stylesheet" type="text/css" href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;custom.css">

</head>

<body>

<header class="box-shadow">


<a href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;">
<div class="logo">
<img src="https:&#x2F;&#x2F;trunkrs.dev&#x2F;rustacean-flat-happy.svg" alt="logo">
Trunk
</div>
</a>

<nav>

<a class="nav-item subtitle-text" href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;assets&#x2F;">Assets</a>

<a class="nav-item subtitle-text" href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;configuration&#x2F;">Configuration</a>

<a class="nav-item subtitle-text" href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;commands&#x2F;">Commands</a>

<a class="nav-item subtitle-text" href="https:&#x2F;&#x2F;trunkrs.dev&#x2F;advanced&#x2F;">Advanced</a>



<a class="nav-item subtitle-text" href="https:&#x2F;&#x2F;github.com&#x2F;trunk-rs&#x2F;trunk">GitHub</a>


</nav>

</header>


<main>





<div class="toc">
<div class="toc-sticky">

<div class="toc-item">
<a class="subtext" href="https://trunkrs.dev/advanced/#javascript-interoperability">JavaScript interoperability</a>
</div>


<div class="toc-item">
<a class="subtext" href="https://trunkrs.dev/advanced/#library-crate">Library crate</a>
</div>


<div class="toc-item">
<a class="subtext" href="https://trunkrs.dev/advanced/#initializer">Initializer</a>
</div>


<div class="toc-item">
<a class="subtext" href="https://trunkrs.dev/advanced/#update-check">Update check</a>
</div>


<div class="toc-item">
<a class="subtext" href="https://trunkrs.dev/advanced/#base-urls-public-urls-paths-reverse-proxies">Base URLs, public URLs, paths &amp; reverse proxies</a>
</div>


</div>
</div>



<div class="content text">

<div class="heading-text">Advanced topics</div>
<h2 id="javascript-interoperability">JavaScript interoperability</h2>
<p>Trunk will create the necessary JavaScript code to bootstrap and run the WebAssembly based application. It will also
include all JavaScript snippets generated by <code>wasm-bindgen</code> for interfacing with JavaScript functionality.</p>
<p>By default, functions exported from Rust, using <code>wasm-bingen</code>, can be accessed in the JavaScript code through the global
variable <code>window.wasmBindings</code>. This behavior can be disabled, and the name can be customized. For more information
see the <a href="https://trunkrs.dev/assets/#rust"><code>rust</code> asset type</a>.</p>
<h2 id="library-crate">Library crate</h2>
<p>Aside from having a <code>main</code> function, it is also possible to up your project as a <code>cdylib</code> project. In order to do that,
add the following to your <code>Cargo.toml</code>:</p>
<pre><code>[lib]
crate-type = [&quot;cdylib&quot;, &quot;rlib&quot;]
</code></pre>
<p>And then, define the entrypoint in your <code>lib.rs</code> like (does not need to be <code>async</code>):</p>
<pre><code>#[wasm_bindgen(start)]
pub async fn run() {}
</code></pre>
<h2 id="initializer">Initializer</h2>
<p>Since: <code>0.19.0-alpha.1</code>.</p>
<p>Trunk supports tapping into the initialization process of the WASM application. By
default, this is not active and works the same way as with previous versions.</p>
<p>The default process is that trunk injects a small JavaScript snippet, which imports the JavaScript loader generated
by <code>wasm_bindgen</code> and calls the <code>init</code> method. That will fetch the WASM blob and run it.</p>
<p>The downside with is, that during this process, there's no feedback to the user. Neither when it takes a bit longer to
load the WASM file, nor when something goes wrong.</p>
<p>Now it is possible to tap into this process by setting <code>data-initializer</code> to a JavaScript module file. This module file
is required to (default) export a function, which returns the &quot;initializer&quot; instance. Here is an example:</p>
<pre><code>export default function myInitializer () {
return {
onStart: () =&gt; {
// called when the loading starts
},
onProgress: ({current, total}) =&gt; {
// the progress while loading, will be called periodically.
// &quot;current&quot; will contain the number of bytes of the WASM already loaded
// &quot;total&quot; will either contain the total number of bytes expected for the WASM, or if the server did not provide
// the content-length header it will contain 0.
},
onComplete: () =&gt; {
// called when the initialization is complete (successfully or failed)
},
onSuccess: (wasm) =&gt; {
// called when the initialization is completed successfully, receives the `wasm` instance
},
onFailure: (error) =&gt; {
// called when the initialization is completed with an error, receives the `error`
}
}
};
</code></pre>
<p>For a full example, see: <a href="https://github.com/trunk-rs/trunk/examples/initializer">https://github.com/trunk-rs/trunk/examples/initializer</a>.</p>
<h2 id="update-check">Update check</h2>
<p>Since: <code>0.19.0-alpha.2</code>.</p>
<p>Trunk has an update check built in. By default, it will check the <code>trunk</code> crate on <code>crates.io</code> for a newer
(non pre-release) version. If one is found, the information will be shown in the command line.</p>
<p>This check can be disabled entirely, but not enabled the cargo feature <code>update_check</code>. It can also be disabled during
runtime using the environment variable <code>TRUNK_SKIP_VERSION_CHECK</code>, or using the command line switch
<code>--skip-version-check</code>.</p>
<p>The check is only performed every 24 hours.</p>
<h2 id="base-urls-public-urls-paths-reverse-proxies">Base URLs, public URLs, paths &amp; reverse proxies</h2>
<p>Since: <code>0.19.0-alpha.3</code>.</p>
<p>Originally <code>trunk</code> had a single <code>--public-url</code>, which allowed to set the base URL of the hosted application.
Plain and simple. This was a prefix for all URLs generated and acted as a base for <code>trunk serve</code>.</p>
<p>Unfortunately, life isn't that simple and naming is hard.</p>
<p>Today <code>trunk</code> was three paths:</p>
<ul>
<li>The &quot;public base URL&quot;: acting as a prefix for all generated URLs</li>
<li>The &quot;serve base&quot;: acting as a scope/prefix for all things served by <code>trunk serve</code></li>
<li>The &quot;websocket base&quot;: acting as a base path for the auto-reload websocket</li>
</ul>
<p>All three can be configured, but there are reasonable defaults in place. By default, the serve base and websocket base
default to the absolute path of the public base. The public base will have a slash appended if it doesn't have one. The
public base can be one of:</p>
<ul>
<li>Unset/nothing/default (meaning <code>/</code>)</li>
<li>An absolute URL (e.g. <code>http://domain/path/app</code>)</li>
<li>An absolute path (e.g. <code>/path/app</code>)</li>
<li>A relative path (e.g. <code>foo</code> or <code>./</code>)</li>
</ul>
<p>If the public base is an absolute URL, then the path of that URL will be used as serve and websocket base. If the public
base is a relative path, then it will be turned into an absolute one. Both approaches might result in a dysfunctional
application, based on your environment. There will be a warning on the console. However, by providing an explicit
value using serve-base or ws-base, this can be fixed.</p>
<p>Why is this necessary and when is it useful? It's mostly there to provide all the knobs/configurations for the case
that weren't considered. The magic of public-url worked for many, but not for all. To support such cases, it
is now possible to tweak all the settings, at the cost of more complexity. Having reasonable defaults should keep it
simple for the simple cases.</p>
<p>An example use case is a reverse proxy <em>in front</em> of <code>trunk serve</code>, which can't be configured to serve the trunk
websocket at the location <code>trunk serve</code> expects it. Now, it is possible to have <code>--public-url</code> to choose the base when
generating links, so that it looks correct when being served by the proxy. But also use <code>--serve-base /</code> to keep
serving resource from the root.</p>


</div>

</main>


<footer>
<p>
<small class="subtext text-center">
<a href="https://github.com/trunk-rs/trunk">Trunk Maintainers</a> © 2024
</small>
</p>
<p class="subtext text-center">
Ferris the crab is public domain. This Ferris can be found at
<a href="https://rustacean.net/">rustacean.net</a>
and in the hearts of Rust users throughout the galaxy!
</p>
<p class="subtext text-center">
Join us, resistance is futile
<a href="https://discord.gg/JEPdBujTDr"><img
src="https://img.shields.io/discord/793890238267260958?logo=discord&style=flat-square"
style="vertical-align:text-bottom;"
alt="Discord Chat" /></a>
</p>
</footer>

</body>
<script>
function highlightNav(heading) {
let pathname = location.pathname;
document.querySelectorAll(".toc a").forEach((item) => {
item.classList.remove("active");
});
document.querySelector(".toc a[href$='" + pathname + "#" + heading + "']").classList.add("active");
}

let currentHeading = "";
window.onscroll = function () {
let h = document.querySelectorAll("h1,h2,h3,h4,h5,h6");
let elementArr = [];

h.forEach(item => {
if (item.id !== "") {
elementArr[item.id] = item.getBoundingClientRect().top;
}
});
elementArr.sort();
for (let key in elementArr) {
if (!elementArr.hasOwnProperty(key)) {
continue;
}
if (elementArr[key] > 0 && elementArr[key] < 300) {
if (currentHeading !== key) {
highlightNav(key);
currentHeading = key;
}
break;
}
}
}
</script>

</html>
Loading

0 comments on commit 5879608

Please sign in to comment.