stdweb

A standard library for the client-side Web

3,459

178

3,459

134

View on GitHub

Top Related Projects

wasm-bindgen

8,610

Facilitating high-level interactions between Wasm modules and JavaScript

yew

32,087

Rust / Wasm framework for creating reliable and efficient web applications

seed

3,838

A Rust framework for creating web apps

gloo

1,928

A modular toolkit for building fast, reliable Web applications and libraries with Rust and WASM

wasm-pack

7,036

📦✨ your favorite rust -> wasm workflow tool!

Quick Overview

The stdweb crate provides a way to interact with the Web APIs from Rust code, allowing developers to build full-fledged web applications using Rust. It aims to provide a seamless integration between Rust and the browser's JavaScript environment.

Pros

Seamless Integration: stdweb provides a Rust-idiomatic API that closely matches the browser's Web APIs, making it easy for Rust developers to work with the web platform.
Cross-Compilation: Rust's cross-compilation capabilities allow stdweb to be used to build web applications that can run on a variety of platforms and devices.
Performance: Rust's focus on performance and safety translates to efficient web applications built with stdweb.
Ecosystem Integration: stdweb integrates well with other Rust crates, allowing developers to leverage the broader Rust ecosystem for their web development needs.

Cons

Browser Support: While stdweb supports a wide range of browsers, it may not work with all browsers or browser versions, especially older ones.
Dependency Management: The stdweb crate has a relatively large number of dependencies, which can make dependency management more complex.
Learning Curve: Developers new to Rust may face a steeper learning curve when working with stdweb, as they need to understand both Rust and the web platform.
Maturity: Compared to more established web development frameworks and libraries, stdweb is a relatively young project, which may mean fewer resources and community support.

Code Examples

Rendering a Simple HTML Element

use stdweb::web::document;
use stdweb::web::html_element::DivElement;

fn main() {
    stdweb::initialize();
    let div: DivElement = document().create_element("div").unwrap().try_into().unwrap();
    div.set_inner_html("Hello, World!");
    document().body().append_child(&div);
    stdweb::event_loop();
}

This code creates a new div element, sets its inner HTML to "Hello, World!", and appends it to the document's body.

Handling User Interactions

use stdweb::web::document;
use stdweb::web::html_element::ButtonElement;
use stdweb::web::event::ClickEvent;

fn main() {
    stdweb::initialize();
    let button: ButtonElement = document().create_element("button").unwrap().try_into().unwrap();
    button.set_inner_html("Click me!");

    let onclick_callback = |_: ClickEvent| {
        js! { alert("You clicked the button!"); }
    };

    button.add_event_listener(onclick_callback);
    document().body().append_child(&button);
    stdweb::event_loop();
}

This code creates a button element, sets its inner HTML, and adds a click event listener that displays an alert when the button is clicked.

Interacting with the Browser's Web APIs

use stdweb::web::{document, IParentNode, IWindowObject};
use stdweb::web::window;

fn main() {
    stdweb::initialize();
    let title = document().title();
    println!("The current page title is: {}", title);

    let width = window().inner_width();
    let height = window().inner_height();
    println!("The current window size is: {}x{}", width, height);

    stdweb::event_loop();
}

This code retrieves the current page title and the size of the browser window, and prints the information to the console.

Getting Started

To get started with stdweb, you'll need to have Rust installed on your system. You can then add the stdweb crate to your Cargo.toml file:

[dependencies]
stdweb = "0.4.20"

Next, you can start writing your web application using the stdweb APIs. Here's a simple example that creates a button and displays an alert when it's clicked:

use stdweb::web::document;
use stdweb::web::

Competitor Comparisons

wasm-bindgen

8,610

Facilitating high-level interactions between Wasm modules and JavaScript

Pros of wasm-bindgen

More actively maintained and widely adopted in the Rust ecosystem
Offers better integration with JavaScript tooling and bundlers
Supports a wider range of JavaScript types and features

Cons of wasm-bindgen

Steeper learning curve for beginners
Requires more boilerplate code for simple use cases
Can be more verbose for certain tasks

Code Comparison

stdweb:

#[macro_use]
extern crate stdweb;
use stdweb::web::Window;

fn main() {
    stdweb::initialize();
    let window: Window = stdweb::web::window();
    js! { console.log(@{window.location().href()}); }
}

wasm-bindgen:

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(js_namespace = console)]
    fn log(s: &str);
}

#[wasm_bindgen(start)]
pub fn main() {
    log("Hello from Rust!");
}

Summary

While stdweb provides a simpler API for basic Web interop, wasm-bindgen offers more comprehensive JavaScript integration and is better suited for complex projects. stdweb's syntax may be more intuitive for some developers, but wasm-bindgen's approach aligns more closely with the direction of the Rust and WebAssembly ecosystem.

yew

32,087

Rust / Wasm framework for creating reliable and efficient web applications

Pros of Yew

More active development and larger community support
Better performance due to its virtual DOM implementation
Comprehensive documentation and examples

Cons of Yew

Steeper learning curve for developers new to Rust and web development
Larger bundle sizes compared to simpler alternatives

Code Comparison

Yew:

use yew::prelude::*;

#[function_component(App)]
fn app() -> Html {
    html! { <h1>{"Hello, World!"}</h1> }
}

stdweb:

use stdweb::web::document;
use stdweb::unstable::TryInto;

fn main() {
    let body: web::Element = document().body().unwrap();
    body.append_html("<h1>Hello, World!</h1>");
}

Summary

Yew is a more modern and feature-rich framework for building client-side web applications in Rust. It offers better performance and a more active ecosystem compared to stdweb. However, it may have a steeper learning curve and result in larger bundle sizes.

stdweb, on the other hand, provides a simpler approach to web development in Rust, with a more straightforward API. It may be easier for beginners to grasp but lacks some of the advanced features and optimizations found in Yew.

The choice between the two depends on the project requirements, developer experience, and desired level of control over the application's structure and performance.

seed

3,838

A Rust framework for creating web apps

Pros of Seed

More actively maintained with regular updates
Focuses on a complete frontend framework, offering a more opinionated structure
Better documentation and examples for getting started

Cons of Seed

Steeper learning curve for developers new to Rust web development
Less flexibility compared to the lower-level approach of stdweb
Potentially larger bundle sizes due to included framework features

Code Comparison

Seed example:

#[derive(Default)]
struct Model {
    count: i32,
}

fn update(msg: Msg, model: &mut Model, _: &mut impl Orders<Msg>) {
    match msg {
        Msg::Increment => model.count += 1,
    }
}

stdweb example:

#[derive(Clone, Debug)]
struct Model {
    count: i32,
}

fn update(model: &mut Model, msg: Msg) {
    match msg {
        Msg::Increment => model.count += 1,
    }
}

Summary

Seed provides a more comprehensive framework for building web applications in Rust, offering better documentation and a more structured approach. However, it may be less flexible and have a steeper learning curve compared to stdweb. stdweb, on the other hand, offers a lower-level interface to web APIs, providing more flexibility but requiring more manual setup and configuration.

gloo

1,928

A modular toolkit for building fast, reliable Web applications and libraries with Rust and WASM

Error generating comparison

wasm-pack

7,036

📦✨ your favorite rust -> wasm workflow tool!

Pros of wasm-pack

Officially supported by the Rust and WebAssembly Working Group
Provides a complete toolchain for building, testing, and publishing Rust-generated WebAssembly
Integrates well with npm and JavaScript ecosystems

Cons of wasm-pack

Steeper learning curve for developers new to Rust and WebAssembly
May require additional configuration for complex projects
Less flexible for custom WebAssembly setups compared to stdweb

Code Comparison

stdweb:

#[macro_use]
extern crate stdweb;

use stdweb::web::Window;

fn main() {
    stdweb::initialize();
    let window: Window = stdweb::web::window();
    js! { console.log("Hello from stdweb!"); }
}

wasm-pack:

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn greet() {
    web_sys::console::log_1(&"Hello from wasm-pack!".into());
}

The stdweb example uses a macro-based approach for JavaScript interop, while wasm-pack relies on wasm-bindgen and web-sys for more idiomatic Rust code. wasm-pack's approach is generally considered more maintainable and type-safe, but may require more setup initially.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

A standard library for the client-side Web

The goal of this crate is to provide Rust bindings to the Web APIs and to allow a high degree of interoperability between Rust and JavaScript.

Donate

Patrons

This software was brought to you thanks to these wonderful people:

Embark Studios
Joe Narvaez
Eduard Knyshov
Anselm Eickhoff
Johan Andersson
Stephen Sugden
is8ac

Thank you!

Examples

You can directly embed JavaScript code into Rust:

let message = "Hello, ä¸ç!";
let result = js! {
    alert( @{message} );
    return 2 + 2 * 2;
};

println!( "2 + 2 * 2 = {:?}", result );

Closures are also supported:

let print_hello = |name: String| {
    println!( "Hello, {}!", name );
};

js! {
    var print_hello = @{print_hello};
    print_hello( "Bob" );
    print_hello.drop(); // Necessary to clean up the closure on Rust's side.
}

You can also pass arbitrary structures thanks to serde:

#[derive(Serialize)]
struct Person {
    name: String,
    age: i32
}

js_serializable!( Person );

js! {
    var person = @{person};
    console.log( person.name + " is " + person.age + " years old." );
};

This crate also exposes a number of Web APIs, for example:

let button = document().query_selector( "#hide-button" ).unwrap().unwrap();
button.add_event_listener( move |_: ClickEvent| {
    for anchor in document().query_selector_all( "#main a" ) {
        js!( @{anchor}.style = "display: none;"; );
    }
});

Exposing Rust functions to JavaScript is supported too:

#[js_export]
fn hash( string: String ) -> String {
    let mut hasher = Sha1::new();
    hasher.update( string.as_bytes() );
    hasher.digest().to_string()
}

Then you can do this from Node.js:

var hasher = require( "hasher.js" ); // Where `hasher.js` is generated from Rust code.
console.log( hasher.hash( "Hello world!" ) );

Or you can take the same .js file and use it in a web browser:

<script src="hasher.js"></script>
<script>
    Rust.hasher.then( function( hasher ) {
        console.log( hasher.hash( "Hello world!" ) );
    });
</script>

If you're using Parcel you can also use our experimental Parcel plugin; first do this in your existing Parcel project:

$ npm install --save parcel-plugin-cargo-web

And then simply:

import hasher from "./hasher/Cargo.toml";
console.log( hasher.hash( "Hello world!" ) );

Design goals

Expose a full suite of Web APIs as exposed by web browsers.
Try to follow the original JavaScript conventions and structure as much as possible, except in cases where doing otherwise results in a clearly superior design.
Be a building block from which higher level frameworks and libraries can be built.
Make it convenient and easy to embed JavaScript code directly into Rust and to marshal data between the two.
Integrate with the wider Rust ecosystem, e.g. support marshaling of structs which implement serde's Serializable.
Put Rust in the driver's seat where a non-trivial Web application can be written without touching JavaScript at all.
Allow Rust to take part in the upcoming WebAssembly (re)volution.
Make it possible to trivially create standalone libraries which are easily callable from JavaScript.

Getting started

Take a look at some of the examples:

examples/minimal - a totally minimal example which calls alert
examples/todomvc - a naively implemented TodoMVC application; shows how to call into the DOM
examples/hasher - shows how to export Rust functions to JavaScript and how to call them from a vanilla web browser environment or from Nodejs
examples/hasher-parcel - shows how to import and call exported Rust functions in a Parcel project
pinky-web - an NES emulator; you can play with the precompiled version here

The API documentation is also available for you to look at.

Running the examples

Install cargo-web:
```
$ cargo install -f cargo-web
```
Go into examples/todomvc and start the example using one of these commands:
- Compile to WebAssembly using Rust's native WebAssembly backend:
```
$ cargo web start --target=wasm32-unknown-unknown
```
- Compile to asm.js using Emscripten:
```
$ cargo web start --target=asmjs-unknown-emscripten
```
- Compile to WebAssembly using Emscripten:
```
$ cargo web start --target=wasm32-unknown-emscripten
```
Visit http://localhost:8000 with your browser.

For the *-emscripten targets cargo-web is not necessary, however the native wasm32-unknown-unknown which doesn't need Emscripten requires cargo-web to work!

Changelog

stdweb 0.4.20
- Compatibility with the newest wasm-bindgen
- New events:
  - FullscreenChangeEvent
stdweb 0.4.19
- New methods:
  - Document::fullscreen_enabled
  - Document::fullscreen_element
  - InputElement::selection_start
  - InputElement::selection_end
  - InputElement::set_selection_start
  - InputElement::set_selection_end
  - Object::to_iter
  - Window::confirm
- &Arrays can now be converted to Vecs through TryFrom
- The runtime should now be compatible with newer versions of Emscripten
- The unstable futures-related APIs were updated to work with the latest nightlies
- The syn dependency was updated to version 1
stdweb 0.4.18
- The js! macro can now be imported with an use
- New events:
  - BeforeUnloadEvent
  - UnloadEvent
- New methods:
  - IBlob::slice
  - IBlob::slice_with_content_type
  - IWindowOrWorker::set_clearable_timeout
stdweb 0.4.17
- The unstable futures-related APIs were updated to work with the latest nightlies
stdweb 0.4.16
- Initial wasm-bindgen compatibility; you can now use stdweb in projects using wasm-bindgen
- Minimum supported Rust version is now 1.33.0
- Minimum required cargo-web version is now 0.6.24
stdweb 0.4.15
- The unstable futures-related APIs were updated to work with the latest nightlies
- New types:
  - FormData
  - FormDataEntry
  - MouseButtonsState
- New methods:
  - Blob::new
stdweb 0.4.14
- The js! macro now generates slightly more efficient code if you're not returning anything from your JS snippet. This makes it unnecessary to add the @(no_return) annotation in the vast majority of cases.
- New types:
  - File
stdweb 0.4.13
- Fixed the procedural js! macro's whitespace handling
- New types:
  - ITouchEvent
  - Touch
  - TouchType
- New events:
  - TouchEvent
  - TouchMove
  - TouchLeave
  - TouchEnter
  - TouchEnd
  - TouchCancel
  - TouchStart
- New methods:
  - XmlHttpRequest::set_response_type
stdweb 0.4.12
- Improved diagnostics when trying to compile for the wasm32-unknown-unknown target without cargo-web
stdweb 0.4.11
- The minimum required Rust version is now 1.30.1
- The minimum required cargo-web version is now 0.6.22
- wasm32-unknown-unknown is now officially supported on stable Rust
- Debug builds on wasm32-unknown-unknown are now supported
- The js! macro is now partially implemented using a procedural macro
- String decoding/encoding is now a lot faster due to the use of native codec APIs
- New methods:
  - Document::import_node
  - IElement::slot
  - IElement::attach_shadow
  - IElement::shadow_root
- New types:
  - ISlotable
  - ShadowRoot
  - ShadowRootMode
  - TemplateElement
  - SlotElement
- New events:
  - SlotChangeEvent
- IParentNode::query_selector and IParentNode::query_selector_all now return a proper error type
stdweb 0.4.10, stdweb-derive 0.5.1
- New methods:
  - IElement::insert_adjacent_html
  - IElement::insert_html_before
  - IElement::insert_html_after
  - IElement::prepend_html
  - IElement::append_html
  - IElement::namespace_uri
  - IElement::closest
  - Document::create_element_ns
  - Window::get_selection
- New types:
  - AbortError
  - SelectionType
  - Selection
  - Range
- The error messages for failed type conversions are now improved
- The error type of failed conversions (when using .try_into()/.try_from()) is now convertible into a TypeError
- Aggregate error types (like, e.g. DrawImageError) are now serializable through the js! macro
- TypeError is now fixed (it was incorrectly treated as a DOMException)
- Number can now be converted into f64 with .into()/.from()
- Added Mut, which is a new wrapper type for safely passing FnMut closures into the js! macro; it is optional for now, however the usage of this wrapper type will be mandatory in the future!
- FnMut closures cannot be called recursively anymore
- #[derive(ReferenceType)] now supports a limited subset of generic types
- Asynchronous unit tests are now supported with a new #[async_test] attribute macro (nightly only)
- Updated to futures 0.3 (nightly only)
stdweb 0.4.9, stdweb-derive 0.5.0
- Performance improvements; serialization through serde is now twice as fast
- New events:
  - ScrollEvent
  - DragRelatedEvent
  - DragEvent
  - DragStartEvent
  - DragEndEvent
  - DragEnterEvent
  - DragLeaveEvent
  - DragOverEvent
  - DragExitEvent
  - DragDropEvent
- New types:
  - DataTransfer
  - EffectAllowed
  - DropEffect
  - DataTransferItemList
  - DataTransferItem
  - DataTransferItemKind
  - IDragEvent
- Values can now be converted to Option< Serde< T > > with try_into
- Deserialization of numbers through serde now works in the majority of cases allowing types other than i32 and f64 to be used
- All of the events are now more strongly-typed
  - Previously in was possible to deserialize e.g. a keyup event as a KeyDownEvent since only the event's JS type was checked and both keyup and keydown share the same JS type (KeyboardEvent). From now on the type field of the event is also checked, so such conversions are not allowed anymore.
0.4.8
- Fixed compilation on the newest nightly when targeting wasm32-unknown-unknown
- New events:
  - PointerLockChangeEvent
  - PointerLockErrorEvent
  - MouseWheelEvent
- New types:
  - MouseWheelDeltaMode
  - XhrResponseType
- New methods:
  - XmlHttpRequest::raw_response
  - Window::device_pixel_ratio
  - Document::pointer_lock_element
  - Document::exit_pointer_lock
0.4.7
- New events:
  - AuxClickEvent
  - MouseEnterEvent
  - MouseLeaveEvent
  - ContextMenuEvent
  - SelectionChangeEvent
- New types:
  - FileList
  - FileReaderReadyState
- Implement gamepad APIs:
  - Gamepad
  - GamepadButton
  - GamepadButtonMapping
  - GamepadEvent
- Fixed CanvasRenderingContext2d::clear_rect
- Fixed a leak when creating TypedArrays from Vecs and ArrayBuffers.
0.4.6
- Fix docs.rs again
- New types:
  - SubmitEvent
  - IChildNode
- Fix CanvasElement::to_data_url
0.4.5
- New types:
  - DocumentFragment
  - SelectElement
  - OptionElement
  - HtmlCollection
- New methods:
  - Node::from_html
  - Value::is_null
- Expose enums:
  - SocketMessageData
  - NodeType
- Update to futures 0.2
0.4.4
- Fix docs.rs (hopefully).
- New methods:
  - Location::origin
  - Location::protocol
  - Location::host
  - Location::hostname
  - Location::port
  - Location::pathname
  - Location::search
- These now return SecurityError in the error case:
  - Location::hash
  - Location::href
0.4.3
- Objects which cannot be used as keys in a WeakMap should be supported now (e.g. some of the WebGL-related objects under Firefox)
- New methods:
  - Element::get_bounding_client_rect
  - Element::scroll_top
  - Element::scroll_left
  - Window::page_x_offset
  - Window::page_y_offset
  - NodeList::item
  - Document::body
  - Document::head
  - Document::title
  - Document::set_title
  - IMouseEvent::offset_x
  - IMouseEvent::offset_y
- Expose more canvas related types:
  - CompositeOperation
  - LineCap
  - LineJoin
  - Repetition
  - TextAlign
  - TextBaseline
- Expose canvas related error types: AddColorStopError, DrawImageError, GetImageDataError
- New events:
  - MouseOverEvent
  - MouseOutEvent
  - PointerOverEvent
  - PointerEnterEvent
  - PointerDownEvent
  - PointerMoveEvent
  - PointerUpEvent
  - PointerCancelEvent
  - PointerOutEvent
  - PointerLeaveEvent
  - GotPointerCaptureEvent
  - LostPointerCaptureEvent
- New interface for pointer events: IPointerEvent
0.4.2
- Fixed a leak when deserializing references
- Fixed CanvasRenderingContext2d::get_canvas
- Exposed FillRule and SocketReadyState
- New attribute related methods added to IElement
- New Date bindings
0.4.1
- Support for newest nightly Rust on wasm32-unknown-unknown
- Exposed SocketBinaryType enum
- New canvas APIs:
  - Numerous new methods for CanvasRenderingContext2d
  - New types: CanvasGradient, CanvasPattern, CanvasStyle, ImageData, TextMetrics
- New error types: IndexSizeError, NotSupportedError, TypeError
0.4
- (breaking change) Removed Array and Object variants from Value; these are now treated as References
- (breaking change) The Value has an extra variant: Symbol
- (breaking change) Removed:
  - InputElement::set_kind
  - InputElement::files
- (breaking change) Renamed:
  - KeydownEvent -> KeyDownEvent
  - KeyupEvent -> KeyUpEvent
  - KeypressEvent -> KeyPressEvent
  - ReadyState -> FileReaderReadyState
  - InputElement::value -> InputElement::raw_value
  - InputElement::set_value -> InputElement::set_raw_value
- (breaking change) ArrayBuffer::new now takes an u64 argument
- (breaking change) InputElement::set_raw_value now takes &str instead of Into< Value >
- (breaking change) Changed return types:
  - Every method which returned usize now returns u32
  - INode::remove_child now returns Node in the Ok case
  - The following now return an u64:
    - ArrayBuffer::len
  - The following now return an i32 instead of f64:
    - IMouseEvent::client_x
    - IMouseEvent::client_y
    - IMouseEvent::movement_x
    - IMouseEvent::movement_y
    - IMouseEvent::screen_x
    - IMouseEvent::screen_y
  - The following now return a Result:
    - INode::insert_before
    - INode::replace_child
    - INode::clone_node
    - StringMap::insert
    - TokenList::add
    - TokenList::remove
    - Document::create_element
    - IEventTarget::dispatch_event
    - FileReader::read_as_text
    - FileReader::read_as_array_buffer
    - FileReader::read_as_text
    - History::replace_state
    - History::go
    - History::back
    - History::forward
    - Location::href
    - Location::hash
    - CanvasElement::to_data_url
    - CanvasElement::to_blob
    - ArrayBuffer::new
  - INode::base_uri now returns a String instead of Option< String >
  - InputElement::raw_value now returns a String instead of Value
- (breaking change) INode::inner_text was moved to IHtmlElement::inner_text
- (breaking change) Document::query_selector and Document::query_selector_all were moved to IParentNode
- (breaking change) IElement::query_selector and IElement::query_selector_all were moved to IParentNode
- (breaking change) Document::get_element_by_id was moved to INonElementParentNode
- (breaking change) A blanket impl for converting between arbitrary reference-like objects using TryFrom/TryInto has been removed
- When building using a recent cargo-web it's not necessary to call stdweb::initialize nor stdweb::event_loop anymore
- Support for cdylib crates on wasm32-unknown-unknown
- New bindings:
  - XmlHttpRequest
  - WebSocket
  - MutationObserver
  - History
  - TextAreaElement
  - CanvasElement
- New event types:
  - MouseDownEvent
  - MouseUpEvent
  - MouseMoveEvent
  - PopStateEvent
  - ResizeEvent
  - ReadyStateChange
  - SocketCloseEvent
  - SocketErrorEvent
  - SocketOpenEvent
  - SocketMessageEvent
- Initial support for the Canvas APIs
- New traits: ReferenceType and InstanceOf
- Add #[derive(ReferenceType)] in stdweb-derive crate; it's now possible to define custom API bindings outside of stdweb
- Add #[js_export] procedural attribute (wasm32-unknown-unknown only)
- Add DomException and subtypes for passing around JavaScript exceptions
- IElement now inherits from INode
- Every interface now inherits from ReferenceType
- Add stdweb::traits module to act as a prelude for use-ing all of our interface traits
- Add console! macro
- Most types now implement PartialEq and Eq
0.3
- (breaking change) Deleted ErrorEvent methods
- (breaking change) Renamed:
  - LoadEvent -> ResourceLoadEvent
  - AbortEvent -> ResourceAbortEvent
  - ErrorEvent -> ResourceErrorEvent
- Add UnsafeTypedArray for zero cost slice passing to js!
- Add Once for passing FnOnce closures to js!

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Snippets of documentation which come from Mozilla Developer Network are covered under the CC-BY-SA, version 2.5 or later.

Contributing

See CONTRIBUTING.md

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot