Authored by ivanceras
A quick start guide to Sauron - a framework for writing front and back-end web applications.
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
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
We will be using
wasm-pack to facilitate compiling rust code into web assembly,
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
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 └── src └── lib.rs
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:
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
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
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
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.
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.
update method accepts
Msg as an argument and modify our model
App depending on the variant of
Msg. The return type of
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
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
Append this code the
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>_bg.wasm. In this case, we will have
. ├── 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 -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 w
asm 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!
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.
Thanks to Colin Adams for contributing to this guide.