Deno Fresh WASM: Code Modules in Rust 🦀 # Deno Fresh WASM: Code Modules in Rust 🦀 #

🧱 What are we Building? #

As just mentioned we will be using the photon-rs library within Rust. The main goal is to see an example of integrating Rust WASM into Deno, so we will keep the Rust side simple. In fact, the main Rust function will only have 18 lines of code. This means you can follow along even with minimal Rust knowledge.

The Rust WASM module will generate a Base64 low resolution image placeholder from an image file saved within our project. On a slow connection, it might take a couple of seconds for the full-sized image to load. We show that Base64 image placeholder in the interim. This is a nice pattern to use on websites as it allows you to reduce Cumulative Layout Shift as well as make the page look more interactive, while still loading. Overall this contributes to a better user experience.

You can follow along starting from scratch or just read and get the code for the completed project in the Rodney Lab GitHub repo (link further down).

🍋 Spinning up a Fresh Deno Project #

To get going let’s spin up a fresh Deno project:

    
deno run -A -r https://fresh.deno.dev my-fresh-app && cd $_
deno task start

  

If this is your first time using Deno see the post on Getting Started with Deno Fresh to get Deno up and running on your system.

Answer the prompts to best suit your own needs. The code below just uses vanilla CSS so there is no need to set up Tailwind support if you are not a fan. Once it is running you can jump to http://localhost:8000 in your browser to see the skeleton project.

⚙️ Setting up the Project for Rust WASM #

If you are already familiar with Rust WASM, you might have used the wasm-pack CLI tool to generate WASM code from Rust. Even though that is not too involved, the Deno wasmbuild module makes things even easier when using Deno. So we go for the wasmbuild approach here. When we issued the deno task start command above this ran the start script defined in deno.json in the project root directory. We will update that file to add a new wasmbuild script:

    
1 {
2   "lock": false,
3   "tasks": {
4     "check": "deno fmt --check && deno lint && deno check **/*.ts && deno check **/*.tsx",
5     "start": "deno run -A --watch=static/,routes/ dev.ts",
6     "build": "deno run -A dev.ts build",
7     "preview": "deno run -A main.ts",
8     "update": "deno run -A -r https://fresh.deno.dev/update .",
9     "wasmbuild": "deno run -A https://deno.land/x/[email protected]/main.ts"
10   },
11   "lint": {
12     "rules": {
13       "tags": [
14         "fresh",
15         "recommended"
16       ]
17     }
18   },
19   "exclude": [
20     "**/_fresh/*"
21   ],
22   "imports": {
23     "@/": "./",
24     "$fresh/": "https://deno.land/x/[email protected]/",
25     "preact": "https://esm.sh/[email protected]",
26     "preact/": "https://esm.sh/[email protected]/",
27     "@preact/signals": "https://esm.sh/*@preact/[email protected]",
28     "@preact/signals-core": "https://esm.sh/*@preact/[email protected]",
29   },
30   "compilerOptions": {
31     "jsx": "react-jsx",
32     "jsxImportSource": "preact"
33   }
34 }

  

We can use this new script to add a skeleton Rust WASM library to our project:

    
deno task wasmbuild new

  

This will create an rs_lib directory in the project with a Cargo.toml (analogous to node package.json file) file and also the Rust skeleton code (rs_lib/src/lib.rs). We will update these next.

🦀 Rust Code #

To make the photon-rs crate available in the project, we add it to Cargo.toml:

    
1 [package]
2 name = "rs_lib"
3 version = "0.0.1"
4 authors = ["Rodney Johnson <[email protected]>"]
5 edition = "2021"
6 license = "BSD-3-Clause"
7 repository = "https://github.com/rodneylab/deno"
8 description = "Basic image processing"
9  
10 [lib]
11 crate-type = ["cdylib"]
12  
13 [profile.release]
14 codegen-units = 1
15 incremental = true
16 lto = true
17 opt-level = "z"
18  
19 [dependencies]
20 photon-rs = "=0.3.1"
21 wasm-bindgen = "=0.2.84"

  

Note that the wasm-bindgen crate needed to work with WASM in Rust is already listed here. Also worth a mention are the optimisation sensible defaults in the [profile.release] block (lines 13 – 17). If either performance or size is an issue, you might want to tweak these parameters  .

Deno Fresh WASM: Rust Source #

Now you can edit rs_lib/src/lib.rs to look like this:

    
1 use photon_rs::{
2   native::open_image_from_bytes,
3   transform::{resize, SamplingFilter},
4 };
5 use wasm_bindgen::prelude::*;
6  
7 #[wasm_bindgen]
8 extern "C" {
9   // Use `js_namespace` here to bind `console.log(..)` instead of just
10   // `log(..)`
11   #[wasm_bindgen(js_namespace = console)]
12   fn log(s: &str);
13 }
14  
15 macro_rules! console_log {
16     ($($t:tt)*) => (log(&format_args!($($t)*).to_string()))
17 }
18  
19 const PLACEHOLDER_WIDTH: u32 = 10;
20  
21 #[wasm_bindgen]
22 #[must_use]
23 pub fn base64_placeholder(data: &[u8]) -> String {
24   let Ok(image) = open_image_from_bytes(data) else {
25     console_log!("Unable to open image");
26     return String::new();
27   };
28   let aspect_ratio = image.get_width() / image.get_height();
29 
30   resize(
31     &image,
32     PLACEHOLDER_WIDTH,
33     PLACEHOLDER_WIDTH / aspect_ratio,
34     SamplingFilter::Lanczos3,
35   )
36   .get_base64()
37 }

  

Our main module function, which we will call from Deno is base64_placeholder defined from line 21 down. Above that we have use statements for the crates and methods we plan to use right at the top. Between the two is a handy macro for creating console.logs. Although originating from the Rust code, these appear in the console when running our code in Deno. Macros kind of create syntactic sugar in Rust. Other examples you might already have seen are format!, and println!. You can see an example of invoking our macro in line 26. Once you have everything working, feel free to stick a “hello world” console_log on the first line of base64_placeholder to convince yourself this works.

Moving on, base64_placeholder takes the image bytes as an input (we will read the image file into a UInt8Array in the TypeScript code and pass those bytes to this function). Our Rust function uses the image bytes to create an image object. We resize the image so it is 10 pixels wide, preserving the aspect ratio. Finally, we convert that output to a Base64 string and return that. Rust has implicit returns, meaning the last line of a function is what gets returned. In our case that will be the Base64 image string.

🔨 Compiling the Module #

To compile the module, we can use the wasmbuild script again. Note you will need to have Rust set up on your system. This uses wasm-pack under the hood, so as a first step install it, using cargo (if you do not yet have it installed). Cargo is Rust tooling for managing crates (Rust packages). The Rust setup process adds it to your system.

    
cargo install wasm-pack
deno task wasmbuild

  

The second step creates a lib folder in your project (it will be a little slow the first time you run it). The WASM will be in lib/rs_lib_bg.wasm. This is assembly code which is not human-readable. As well as the WASM you have lib/rs_lib.generated.js — the JavaScript code we will use import in the next section. If you scan through that file, you will see the base64_to_image function we created in Rust. Although this is a JavaScript file, it has type information in JSDoc annotations meaning we have types for use in TypeScript in the next section.

Using the Module #

Hopefully this hasn’t been too complicated thus far. Using the module is pretty straightforward. We import it (like any other module), then call its asynchronous instantiate function, and can then use it just like any other import. Here we add a handler to routes/index.tsx to generate the Base64 placeholder, using our new module:

    
1 import { asset, Head } from "$fresh/runtime.ts";
2 import { Handlers, PageProps } from "$fresh/server.ts";
3 import Image from "@/islands/Image.tsx";
4 import { base64_placeholder, instantiate } from "@/lib/rs_lib.generated.js";
5 import { Fragment } from "preact";
6  
7 interface Data {
8   placeholder: string;
9 }
10  
11 export const handler: Handlers<Data | null> = {
12   async GET(_request, context) {
13     try {
14       await instantiate();
15  
16       const data = await Deno.readFile("./content/dinosaur-lemon.png");
17       const placeholder = base64_placeholder(data);
18  
19       return context.render({ placeholder });
20     } catch (error: unknown) {
21       console.error(`Error doing stuff with image file: ${error as string}`);
22       return context.render(null);
23     }
24   },
25 };

  

Note in line 16, we read the image file from disk as binary data into a data which is a UInt8Array. That is all there is to it!

Here is the rest of the home route code and also the Image Preact component which we reference:

    
27 export default function Home(context: PageProps<Data | null>) {
28   const { data } = context;
29   if (!data) {
30     return (
31       <Fragment>
32         <div>Something went wrong!</div>
33       </Fragment>
34     );
35   }
36   const { placeholder } = data;
37 
38   return (
39     <>
40       <Head>
41         <title>Deno Fresh 🍋 Rust WASM</title>
42         <link rel="stylesheet" href={asset("/fonts.css")} />
43         <link rel="stylesheet" href={asset("/global.css")} />
44         <link rel="icon" href={asset("/favicon.ico")} sizes="any" />
45         <link rel="icon" href={asset("/icon.svg")} type="image/svg+xml" />
46         <link rel="apple-touch-icon" href={asset("/apple-touch-icon.png")} />
47         <link rel="manifest" href={asset("/manifest.webmanifest")} />
48         <title>Deno Fresh 🍋 Rust WASM</title>
49         <meta
50           name="description"
51           content="Deno Fresh WASM: how you can code your own WASM modules in Rust 🦀 and easily integrate them into your Deno Fresh 🍋 project."
52         />
53       </Head>
54       <main className="wrapper">
55         <h1 className="heading">FRESH!</h1>
56         <Image
57           src="/content/dinosaur-lemon.png"
58           placeholder={placeholder}
59           alt="Cartoon style image of a dinosaur wiht a mouth full of lemons"
60         />
61       </main>
62     </>
63   );
64 }

  

    
27 import { useEffect, useRef } from "preact/hooks";
28  
29 interface ImageProps {
30   alt: string;
31   placeholder: string;
32   src: string;
33 }
34  
35 export default function Image({ alt, placeholder, src }: ImageProps) {
36   const imageElement = useRef<HTMLImageElement>(null);
37  
38   useEffect(() => {
39     if (imageElement.current) {
40       imageElement.current.src = src;
41     }
42   }, [src]);
43  
44   return (
45     <figure className="image-wrapper">
46       <img
47         ref={imageElement}
48         alt={alt}
49         loading="eager"
50         decoding="async"
51         fetchPriority="high"
52         height="256"
53         width="256"
54         src={placeholder}
55       />
56     </figure>
57   );
58 }

  

🙌🏽 Deno Fresh WASM: Wrapping Up #

In the post we have had a whistle-stop tour of setting up your first Deno WASM project. In particular, we saw:

• how to use wasmbuild to quickly add a Rust WASM module to your Deno project,
• how to add console logs in your WASM Rust code,
• some basic Rust image manipulation.

The complete is in Rodney Lab GitHub repo  . As a next step you might consider publishing your WASM module to deno.land/x so other developers can easily use it. This is something I did with the parsedown module  . It has code I use for the Newsletter and parses Markdown to HTML as well as generate email HTML and plaintext emails. Let me know if you would like to see a short video on publishing a Deno module.

If you want to learn more on wasm-pack, there is a wasm-pack book  as well as some fairly detailed wasm-bindgen docs  . There are a few resources for learning Rust itself in the December newsletter  . Finally, please get in touch if you would like to see more content on Deno and Fresh. I hope you found the content useful and am keen to hear about possible improvements.

🏁 Deno Fresh WASM: Summary #

Can you use the wasm-pack Rust tooling to create WASM modules for Deno? #

wasm-pack tooling does a lot to make creating WASM modules in Rust easy. If you are working in Deno though, you can make your life even easier by using the `wasmbuild` module. This adds skeleton template code to your Deno project. On top you can compile the Rust code from a script within your Deno project. Finally, if you want to take it up a level, you can set Deno to watch your Rust source. That way you can re-compile automatically when the code changes. Under the hood wasmbuild uses wasm-pack so you need to set up both.

Can any Rust code compile to WASM? #

You might find some code does not compile into WASM, especially where the code accesses the file system or needs libraries installed on the end-user’s system. An example of the latter is crates which use openssl. The openssl crate is a wrapper on C code. As a workaround in that case try alternatives which use pure Rust implementations. Having said all that, you should be able to use any JavaScript APIs in your Rust code, so the FileReader API for example is one you should check out if you need to work with files. Be sure to test your code early and often to avoid disappointment!

Is there a size limit for WASM modules? #

Some hosting providers have low limits on maximum size of your generated WASM. Deno deploy has quite generous limits meaning you can run code using even moderately heavy crates. There are some optimisations detailed in the wasm-bindgen docs. Naturally these will only get you so far, but are worth pursuing if you are not far from your target size.

Can you publish your WASM module on deno.land/x? #

Yes you can publish WASM modules to deno.land/x quite easily. This will make your module easily accessible to other developers. You currently need a GitHub account to be able to host your module on deno.lad/x. This process is not too complicated and involves adding a Webhook to your project in GitHub. This helps automatically update the deno.land/x version of your module.

🙏🏽 Deno Fresh WASM: Feedback #

Have you found the post useful? Would you prefer to see posts on another topic instead? Get in touch with ideas for new posts. Also, if you like my writing style, get in touch if I can write some posts for your company site on a consultancy basis. Read on to find ways to get in touch, further below. If you want to support posts similar to this one and can spare a few dollars, euros or pounds, then please consider supporting me through Buy me a Coffee.

Rodney

@askRodney

Love Deno 🍋 Fresh’s modern web features. Just dropped a post showing how you can:

- generate Base64 low res image placeholder in 🦀Rust,
- compile the Rust to WASM in Deno,
- use your WASM right in your Fresh TypeScript code

Hope you find it useful!

https://t.co/RTkwLfgl4u pic.twitter.com/kj35IcMts6

— Rodney (@askRodney) January 18, 2023

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via @askRodney on Twitter, @[email protected]  on Mastodon and also the #rodney  Element Matrix room. Also, see further ways to get in touch with Rodney Lab. I post regularly on Astro as well as SvelteKit. Also, subscribe to the newsletter to keep up-to-date with our latest projects.