Percy

Build frontend browser apps with Rust + WebAssembly. Supports server side rendering.

The Percy Book

This README gives a light introduction to Percy. Check out The Percy Book for a full walk through.

Stable Rust

Percy compiles on stable Rust with one caveat:

On nightly Rust you can create text nodes without quotes.

// Nightly Rust does not require quotes around text nodes.
html! { <div>My text nodes here </div> };

On stable Rust, quotation marks are required.

// Stable Rust requires quotes around text nodes.
html! { <div>{ "My text nodes here " }</div> };

This difference will go away once span locations are stabilized in the Rust compiler - Rust tracking issue.

Getting Started

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

Quickstart - Getting your feet wet

Percy allows you to create applications that only have server side rendering, only client side rendering, or both server and client side rendering.

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
touch app.css

Here's the directory structure:

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

Now edit each file with the following contents:

# contents of build.sh

#!/bin/bash

cd "$(dirname "$0")"

mkdir -p public

cargo build --target wasm32-unknown-unknown
wasm-bindgen target/wasm32-unknown-unknown/debug/client_side_web_app.wasm --no-typescript --target web --out-dir ./public --debug
cp index.html public/
cp app.css public/

// contents of src/lib.rs

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

use percy_dom::prelude::*;

#[wasm_bindgen]
struct App {
  pdom: PercyDom
}

#[wasm_bindgen]
impl App {
    #[wasm_bindgen(constructor)]
    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 pdom = PercyDom::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>

              <button
                class="giant-button"
                onclick=|_event| {
                   web_sys::console::log_1(&"Button Clicked!".into());
                }
              >
                // No need to wrap text in quotation marks (:
                Click me and check your console
              </button>
           </div>
        };

        pdom.update(end_view);

        App { pdom }
    }
}

# contents of Cargo.toml

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

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

[dependencies]
wasm-bindgen = "0.2"
js-sys = "0.3"
percy-dom = "0.9"

[dependencies.web-sys]
version = "0.3"
features = [
    "Document",
    "MouseEvent",
    "Window",
    "console"
]

<!-- contents of index.html -->
<!DOCTYPE html>
<html lang="en">
    <head>
        <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>
    </head>
    <body style='margin: 0; padding: 0; width: 100%; height: 100%;'>
        <script type="module">
            import init, {App} from '/client_side_web_app.js'
        
            async function run ()  {
                await init('/client_side_web_app_bg.wasm')
                new App()
            }
        
            run()
        </script>
    </body>
</html>

/* contents of app.css */
.big {
  font-size: 30px;
}
.blue {
  color: blue;
}
.giant-button {
  font-size: 24px;
  font-weight: bold;
}

Now run

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

# Or any other static file server that supports the application/wasm mime type
cargo install https

chmod +x ./build.sh
./build.sh

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

And you should see the following:

Client side example

Nice work!

More Examples

API Documentation

Contributing

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 :

./test.sh

License

MIT

Project Name	Stars	Repos Using This	Packages Using This	Most Recent Commit	Total Releases	Latest Release	Open Issues	License	Language
Epub.js	5,534	72	41	a month ago	108	February 16, 2022	455	other	JavaScript
Enhanced eBooks in the browser.
Game Programmer Study Notes	3,357			a year ago			1
:anchor: 我的游戏程序员生涯的读书笔记合辑。你可以把它看作一个加强版的Blog。涉及图形学、实时渲染、编程实践、GPU编程、设计模式、软件工程等内容。Keep Reading , Keep Writing , Keep Coding.
Real Time Rendering 3rd Cn Summary Ebook	2,191			5 years ago			4	gpl-3.0
:blue_book: 电子书 -《Real-Time Rendering 3rd》提炼总结 \| 全书共9万7千余字。你可以把它看做中文通俗版的《Real-Time Rendering 3rd》，也可以把它看做《Real-Time Rendering 3rd》的解读版与配套学习伴侣，或者《Real-Time Rendering 4th》的前置阅读材料。
Percy	2,145	3	4	a month ago	22	June 09, 2022	41	apache-2.0	Rust
Build frontend browser apps with Rust + WebAssembly. Supports server side rendering.
Rs_pbrt	769			2 months ago	8	April 20, 2022	3	other	Rust
Rust crate to implement a counterpart to the PBRT book's (3rd edition) C++ code. See also https://www.rs-pbrt.org/about ...
Pbrtbook	631			18 days ago			1	other	TeX
pbrt 中文整合翻译基于物理的渲染：从理论到实现 Physically Based Rendering: From Theory To Implementation
Vfx_good_night_reading	430			5 months ago			1	mit	HTML
:books: Curated collection of good reading about VFX and CG
Openglobe	239			8 years ago			5	other	C#
A 3D engine for virtual globes (think Google Earth or NASA World Wind) designed to illustrate the engine design and rendering techniques described in our book. OpenGlobe is written in C# and uses OpenGL 3.3 core profile (via OpenTK). See the web site linked below for more information
Gpu Pro Books Source Code	234			3 years ago					GLSL
:cd: Source Code Collection of Book <GPU Pro> 1~ 7 \| 《GPU Pro》1~ 7 书本源代码珍藏
Psraytracing	183			5 months ago				apache-2.0	C
A (modern) C++ implementation of the Peter Shirley Ray Tracing mini-books (https://raytracing.github.io). Features a clean project structure, perf. improvements (compared to the original code), multi-core rendering, and more.