16 releases

new 0.2.13 Jul 28, 2021
0.2.12 Jul 25, 2021
0.2.7 Jan 21, 2020
0.2.6 May 24, 2019
0.0.1 Nov 27, 2018

#17 in WebAssembly

Download history 14/week @ 2021-04-09 64/week @ 2021-04-16 22/week @ 2021-04-23 22/week @ 2021-04-30 12/week @ 2021-05-07 20/week @ 2021-05-14 28/week @ 2021-05-21 19/week @ 2021-05-28 26/week @ 2021-06-04 48/week @ 2021-06-11 8/week @ 2021-06-18 17/week @ 2021-06-25 19/week @ 2021-07-02 16/week @ 2021-07-09 54/week @ 2021-07-16 88/week @ 2021-07-23

124 downloads per month
Used in 5 crates (3 directly)


797 lines


Actions Status Build status

Libraries for building interactive frontend browser apps with Rust + WebAssembly. Supports server side rendering.

Percy is collection of tools geared towards building single page web apps entirely in Rust that can also be rendered at the server.

This allows you to build search engine friendly browser applications in Rust.

The Percy Book

Information about all of the libraries and tools can be found in the Percy book.

This README serves as a light introduction - consult the book for a full walk through.

The Percy Book

How does it work?

Well, that depends on the library in question.

At a high level you:

  1. Serve your application from a server (optional)

  2. User loads the page

  3. Page downloads your application compiled to WebAssembly

  4. Page picks up where the server left off by reading state from the window

So the server would render the application into a String of HTML and send that down to the client.

Then the client would take over, re-rendering the application to a DOM Node whenever application state changes.

In a browser our application renders to an HtmlElement, and on the server our application renders to a String.

Getting Started

For a full example of an isomorphic web app in Rust check out the isomorphic example.

The best way to get up to speed is by checking out The Percy Book, but here are some very basic examples to get your feet wet with.

Quickstart - Getting your feet wet

You can create applications that only have server side rendering, client side rendering, or both!

Here's a quick-and-easy working example of client side rendering that you can try right now!

First, Create a new project using

cargo new client-side-web-app --lib
cd client-side-web-app

Add the following files to your project.

touch build.sh
touch index.html

Here's the end directory structure:

├── Cargo.toml
├── build.sh
├── index.html
└── src
    └── lib.rs

Now edit each file with the following contents:

# contents of build.sh


cd "$(dirname "$0")"

mkdir -p public

OUTPUT_CSS=$CSS_FILE wasm-pack build --no-typescript --dev --target no-modules --out-dir ./public
cp index.html public/
// contents of src/lib.rs


use wasm_bindgen::prelude::*;
use web_sys;
use web_sys::MouseEvent;

use css_rs_macro::css;
use virtual_dom_rs::prelude::*;

struct App {
  dom_updater: DomUpdater

impl App {
    pub fn new () -> App {
        let start_view = html! { <div> Hello </div> };

        let window = web_sys::window().unwrap();
        let document = window.document().unwrap();
        let body = document.body().unwrap();

        let mut dom_updater = DomUpdater::new_append_to_mount(start_view, &body);

        let greetings = "Hello, World!";

        let end_view = html! {
           // Use regular Rust comments within your html
           <div class="big blue">
              /* Interpolate values using braces */
              <strong>{ greetings }</strong>

                onclick=|_event: MouseEvent| {
                   web_sys::console::log_1(&"Button Clicked!".into());
                // No need to wrap text in quotation marks (:
                Click me and check your console


        App { dom_updater }

static MY_COMPONENT_CSS: &'static str = css!{r#"
:host {
    font-size: 24px;
    font-weight: bold;

static _MORE_CSS: &'static str = css!{r#"
.big {
  font-size: 30px;

.blue {
  color: blue;
# contents of Cargo.toml

name = "client-side-web-app"
version = "0.1.0"
authors = ["Friends of Percy"]
edition = "2018"

crate-type = ["cdylib"] # Don't forget this!

wasm-bindgen = "0.2.37"
js-sys = "0.3.14"
virtual-dom-rs = "0.6"
css-rs-macro = "0.1"

version = "0.3"
features = [
<!-- contents of index.html -->
<!DOCTYPE html>
<html lang="en">
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel="stylesheet" type="text/css" href="app.css"/>
        <title>Client Side Demo</title>
    <body style='margin: 0; padding: 0; width: 100%; height: 100%;'>
        <script src='/client_side_web_app.js'></script>
            window.wasm_bindgen(`/client_side_web_app_bg.wasm`).then(() => {
                const { App } = window.wasm_bindgen
                new App()

Now run

# Used to compile your Rust code to WebAssembly
cargo install wasm-pack

# Or any other static file server that supports the application/wasm mime type
npm install -g http-server

chmod +x ./build.sh

# Visit localhost:8080 in your browser
http-server ./public --open

And you should see the following:

Client side example

Nice work!

More Examples

API Documentation


Always feel very free to open issues and PRs with any questions / thoughts that you have!

Even if it feels basic or simple - if there's a question on your mind that you can't quickly answer yourself then that's a failure in the documentation.

Much more information on how to contribute to the codebase can be found in the contributing section of The Percy Book!

To Test

To run all of the unit, integration and browser tests, grab the dependencies then :


See Also




~154K SLoC