An Intro to the Sauron web Framework
Authored by ivanceras
A quick start guide to Sauron - a framework for writing front and back-end web applications.
Introduction
Sauron is a versatile framework for designing and writing front and back-end web applications. Sauron uses the rust programming language—it's an ecosystem where rust code can run natively in the back-end and the browser via web assembly.
In a way, developers can write both the front and back-end of an application with fewer lines of code. This is true because a lot of the code, such as data models, can be shared on each side. The ultimate goal of Sauron is to enable developers to write web applications as easily as possible.
Let's walk through an example
Using sauron, we'll show you how to build a simple web app that shows three buttons that the user can click to increment, decrement and reset the counter. Before you start, make sure you have the following installed:
If you haven't already, head over to rustup.rs to install rust. Once rust is installed, the package manager called cargo is automatically available to be used.
You may also need to install the build-essential packages and some libraries needed for wasm-pack.
sudo apt install build-essential libssl-dev pkg-config ca-certificates
We can then easily install the other two prerequisites since they are published as an executable crate in [crates.io](https://crates.io).
We will be using wasm-pack to facilitate compiling rust code into web assembly, wasm for short. This command-line tool will generate the necessary javascript shims, optimize the output, and move the compilation result into an appropriate directory of our project.
cargo install wasm-pack
We will also use basic-http-server to easily serve static files locally.
cargo install basic-http-server
Creating a new project
We will create a new project called counter.
cargo new --lib counter
This will create a new folder counter with some files necessary to be compiled as a rust project. Try to compile this project to test if we installed rust correctly.
cd counter && cargo build
It should successfully compile the project. If you look at Cargo.toml this is what you should see:
Take note of the package name as the filenames of the compiled binary will be derived from it. There is also src/lib.rs which contains a simplistic unit test as a stub code. In summary, there are only two files needed to create a minimum rust library crate: Cargo.toml and src/lib.rs.
.
├── Cargo.toml
└── src
└── lib.rs
Using sauron
Since we're making a web application, we need to specify in Cargo.toml that this crate needed to be compiled as cdylib. While we're at it, add sauron as a dependency.
Next, we modify src/lib.rs by defining our model. Remove the contents of src/lib.rs and put in this code:
We defined struct App as our model, which contains the count. We also added a function new to create an instance of our App which sets the count to 0.
Next, we define the set of actions that our web app will have. We will implement this using enum with the name Msg. Append this code to src/lib.rs .
After that, we will implement the Application trait for our model App. This is a way to define how our app will be displayed on the page with the view method. This also lets us define how the App modifies its model with the update method.
Looking at the code above, there are a few things to notice. First, we specify that we are implementing sauron's Application trait and specify that we will be dealing with Msg as the type of actions or messages that the application will be dealing with.
Second, the view method returns a type Node<Msg> which means it creates an html node where any of its underlying html elements can have event listeners that can emit Msg messages to the program handler. When the user clicks on the increment button, this will emit a Msg::Increment message. The view uses the node macro, which allows you to write an "html-like" code. You can also write the html view using a series of function calls. Refer to these examples for more information on how it's done.
Note: there is also an online tool that can automatically convert your existing html code to work in sauron.
The update method accepts Msg as an argument and modify our model App depending on the variant of Msg. The return type of update is Cmd<Self,Msg> which can be used for emitting a subsequent Msg from the current Msg that is being processed, but for this simple example, we will just use Cmd::none() .
Next, we define an entry point for our wasm web app. The entry point is a function that gets executed when the wasm is loaded into the browser. This is done by annotating a public function with #[wasm_bindgen(start)].
Append this code the src/lib.rs
In this entry point function start, we define how our app will be mounted into the page document. In this case, we're mounting it to the body of the document. The [Program](https://docs.rs/sauron/latest/sauron/struct.Program.html) provides other ways to mount your application into the document.
Compile the project by issuing the following command at the root folder of your project:
wasm-pack build --release --target=web
As mentioned earlier, wasm-pack simplifies the process of compiling rust code for targeting wasm. A folder ./pkg is then created inside our project directory. This contains the resulting compiled files. We only need to pay attention to two files, with their filename derived from the given package name <package_name>.js and <package_name>_bg.wasm. In this case, we will have counter.js and counter_bg.wasm.
.
├── Cargo.toml
├── src
│ └── lib.rs
├── index.html
└── pkg
├── counter.js
└── counter_bg.wasm
Next, we need to link our wasm web app to our index page. Create an index.html file in the root folder counter of our project.
Make sure that the filename of the referenced file ./pkg/counter.js in the import matches the package name of your web app counter. If you later rename the package, double-check this part.
Finally, serve the files using basic-http-server.
basic-http-server -a 0.0.0.0:4000
Then navigate your browser to http://localhost:4000 to see and interact with the app.
Congratulations!🥳 you have successfully created your first wasm web app using sauron.
This is the first in our series on sauron, where we‘ll explore version updates, other topics like progressive rendering, and how to use sauron to build dapps in various blockchain ecosystems. Stay tuned!
About ChainSafe
ChainSafe is a leading blockchain research and development firm specializing in infrastructure solutions for the decentralized web. Alongside client implementations for Ethereum, Polkadot, Filecoin, and Mina, we're building a portfolio of web3 products - Files, Storage, web3.unity, and more. As part of our mission to build innovative products for users and better tooling for developers, ChainSafe embodies an open source and community-oriented ethos. To learn more, click here.
Website |Twitter |Linkedin |GitHub |Discord |YouTube
Acknowledgments
Thanks to Colin Adams for contributing to this guide.
