wasm-react 🦀⚛️
WASM bindings for React.
Introduction
This library enables you to write and use React components in Rust, which then can be exported to JS to be reused or rendered.
Why React?
React is one of the most popular UI framework for JS with a thriving community and lots of libraries written for it. Standing on the shoulder of giants, you will be able to write complex frontend applications with Rust.
Goals
- Provide Rust bindings for the public API of
react
as close to the original API as possible, but with Rust in mind. - Provide an ergonomic way to write components.
- Provide ways to interact with components written in JS.
Non-Goals
- Provide bindings for any other library than
react
, e.g.react-dom
. - Provide a reimplementation of the reconciliation algorithm or another runtime.
- Emphasis on performance.
Getting Started
Make sure you have Rust and Cargo installed. You can include wasm-react
by
adding it to your Cargo.toml
. Furthermore, if you want to expose your Rust
components to JS, you also need wasm-bindgen
and install wasm-pack
.
[]
= "0.1"
= "0.2"
Creating a Component
First, you need to define a struct for the props of your component. To define
the render function, you need to implement the trait Component
for your
struct:
use ;
Add State
You can use the use_state()
hook to make your component stateful:
use ;
use use_state;
Note that according to the usual Rust rules, the state will be dropped when the
render function returns. use_state()
will prevent that by tying the lifetime
of the state to the lifetime of the component, therefore persisting the state
through the entire lifetime of the component.
Add Event Handlers
To create an event handler, you have to keep the lifetime of the closure beyond
the render function as well, so JS can call it in the future. You can persist a
closure by using the use_callback()
hook:
use ;
use ;
Export Components for JS Consumption
First, you'll need wasm-pack
. You can use export_components!
to export
your Rust component for JS consumption. Requirement is that your component
implements TryFrom<JsValue, Error = JsValue>
.
use ;
use JsValue;
;
export_components!
Use wasm-pack
to compile your Rust code into WASM:
Depending on your JS project structure, you may want to specify the --target
option, see
wasm-pack
documentation.
Assuming you use a bundler that supports JSX and WASM imports in ES modules like Webpack, you can use:
import React from "react";
import from "react-dom/client";
If you use plain ES modules, you can do the following:
import "https://unpkg.com/react/umd/react.production.min.js";
import "https://unpkg.com/react-dom/umd/react-dom.production.min.js";
import init from "./path/to/pkg/project.js";
Import Components for Rust Consumption
You can use import_components!
together with wasm-bindgen
to import JS
components for Rust consumption. First, prepare your JS component:
// /.dummy/myComponents.js
import "https://unpkg.com/react/umd/react.production.min.js";
export
Make sure the component uses the same React runtime as specified for
wasm-react
. Afterwards, use import_components!
:
use ;
use Props;
use *;
import_components!
;
Passing Down State as Prop
Say you define a component with the following struct:
use Rc;
You want to include TaskList
in a container component App
where tasks
is
managed by a state:
use Rc;
use ;
use ;
;
Changing the type of tasks
to fit tasks.value()
doesn't work, since
tasks.value()
returns a non-'static
reference while component structs can
only contain 'static
values. You can clone the underlying Vec
, but this
introduces unnecessary overhead. In this situation you might think you can
simply change the type of TaskList
to a State
:
use Rc;
use ;
use ;
This works as long as the prop tasks
is guaranteed to come from a state. But
this assumption may not hold. You might want to pass on Rc<Vec<Rc<str>>>
or
Memo<Vec<Rc<str>>>
instead in the future or somewhere else. To be as generic
as possible, you can use ValueContainer
:
use Rc;
use ;
use ;
;
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.