Introduction
In this tutorial, we will see how to set up a project with Rust-WASM, and effectively build and deploy a GatsbyJS site 🤓.
According to webassembly.org, WebAssembly (aka WASM) is a binary instruction format for a stack-based virtual machine. In practice, it is a format upon which we can deploy performant code for demanding tasks that run in browsers.
Because WASM is a binary format, we need to compile other languages to it. Common options are C, C++, Rust, and AssemblyScript. This time we'll use Rust for the task.
Requirements
For this project, you'll need Node (preferably with yarn) and Rust installed, as well as gatsby-cli and wasm-pack.
Creating a Gatsby Project
To create our Gatsby project run the following commands
gatsby new tutorial
cd tutorial
yarn start (or npm start)
We can now go to http://localhost:8000/ and see the default gatsby page
Going back to the terminal, we are going to add a couple of dependencies which I will explain as we use them.
yarn add @loadable/component react-hooks-lib
yarn add -D @types/loadable__component
Creating our Rust project
Now that we have Gatsby ready for our purposes we will create our rust project inside tutorial/src.
cd src && cargo new wasm
This will create a default rust project which we can extend to support wasm.
Note: If you don't know anything about rust there is an amazing Youtube Channel where you can learn the basics and beyond.
If everything went right up until this moment, you should be able to do cd wasm and then cargo run, the expected output should be Hello, world!
In order to compile to wasm we need to add the following lines to Cargo.toml
# .
# .
# .
[lib]
crate-type = ["cdylib"]
[dependencies]
wasm-bindgen = "0.2"
Now we need to change our starting point. By default rust will use main.rs but our project will be a library project and therefore the starting point must be lib.rs. (For further explanation refer to this video). To do this, simply delete main.rs and create a new file called lib.rs. We can populate that new file with the snippet from rustwasm guide to verify that everything is working as it should.
use wasm_bindgen::prelude::*;
#[wasm_bindgen]
extern "C" {
fn alert(s: &str);
}
#[wasm_bindgen]
pub fn greet(name: &str) {
alert(&format!("Hello, {}!", name));
}
run wasm-pack build to build our wasm code. You'll see a pkg folder inside wasm, this contains all the files we need, you can take a look at wasm.d.ts to see types declarations.
You should see
export function greet(name: string): void;
Hold on with your rust code for a while because we need to go back to gatsby
Back to Gatsby
Run cd .. (assuming you were on tutorial/src/wasm)
Let's rename tutorial/src/pages/index.js to tutorial/src/pages/index.tsx (Restart gatsby if you get any errors)
Create a types folder inside src and create a file called WASM.ts with the next line:
export type IWASMModule = typeof import("../wasm/pkg/wasm")
This is a bit hacky since, as we will see, WASM must be imported dynamically and Gatsby will have trouble if we don't use a clever hack.
Now back to our index.tsx, we will use loadable to import WASM dynamically,
/* index.tsx */
/*
.
.
.
*/
import loadable from "@loadable/component"
import { IWASMModule } from "../types/WASM"
const WASMModule = loadable.lib(
() => import("" + "../wasm/pkg/wasm") as Promise<IWASMModule>
)
WASMModule is now a component which have a callback as a children, meaning that we can now pass the entire WASM module or only some parts of it as a prop to other components.
As an example we will use a button that calls the greet method.
<WASMModule>
{({ greet }) => <button onClick={() => greet("ruuuuust")}>press me</button>}
</WASMModule>
Note that if you hover over greet you get the exact type
The full code will looks like something like this
import React from "react"
import Layout from "../components/layout"
import SEO from "../components/seo"
import loadable from "@loadable/component"
import { IWASMModule } from "../types/WASM"
const WASMModule = loadable.lib(
() => import("" + "../wasm/pkg/wasm") as Promise<IWASMModule>
)
const IndexPage = () => (
<Layout>
<SEO title="Home" />
<h1>Hi people</h1>
<p>Welcome to your new Gatsby site.</p>
<WASMModule>
{({ greet }) => <button onClick={() => greet("ruuuuust")}>press me</button>}
</WASMModule>
</Layout>
)
export default IndexPage
And if you press the button
Works like a charm 🔥!
Splitting functionality
We want to keep things separated to make a robust solution. To do that we will create a canvas.tsx file inside src/components
We are going to use the useDidMount hook from react-hooks-lib to greet our user, later on we will use it to set up WebGL. We'll also leave a canvas element for future usage.
import React, { FC, } from "react"
import { useDidMount } from "react-hooks-lib"
import { IWASMModule } from "../types/WASM"
type CanvasComponent = FC<{
greet: IWASMModule["greet"]
}>
const Canvas: CanvasComponent = ({ greet }) => {
useDidMount(() => {
greet("from did mount")
})
return (
<>
<p>placeholder for part 2</p>
<canvas width="640" height="480"> </canvas>
</>
)
}
export default Canvas
Back to our index.tsx we import and use the new canvas component.
import React from "react"
import Layout from "../components/layout"
import SEO from "../components/seo"
import loadable from "@loadable/component"
import { IWASMModule } from "../types/WASM"
import Canvas from '../components/canvas'
const WASMModule = loadable.lib(
() => import("" + "../wasm/pkg/wasm") as Promise<IWASMModule>
)
const IndexPage = () => (
<Layout>
<SEO title="Home" />
<h1>Hi people</h1>
<p>Welcome to your new Gatsby site.</p>
<WASMModule>
{({ greet }) => <Canvas greet={greet} />}
</WASMModule>
</Layout>
)
export default IndexPage
Now every time refresh the page we will get
Part 2
We are now ready for part 2 where we will go deeper on rust and also review a bit of WebGL. It may seem like a lot to learn but possibilities are endless.
I will post part 2 in the next couple of days.
If you like it I would love to hear your feedback.
Happy coding!