README.md
1<div align="center">
2
3 <h1><code>wasm-bindgen</code></h1>
4
5 <p>
6 <strong>Facilitating high-level interactions between Wasm modules and JavaScript.</strong>
7 </p>
8
9 <p>
10 <a href="https://dev.azure.com/rustwasm/wasm-bindgen/_build/latest?definitionId=1&branchName=master"><img src="https://img.shields.io/azure-devops/build/rustwasm/wasm-bindgen/1.svg?style=flat-square" alt="Build Status" /></a>
11 <a href="https://crates.io/crates/wasm-bindgen"><img src="https://img.shields.io/crates/v/wasm-bindgen.svg?style=flat-square" alt="Crates.io version" /></a>
12 <a href="https://crates.io/crates/wasm-bindgen"><img src="https://img.shields.io/crates/d/wasm-bindgen.svg?style=flat-square" alt="Download" /></a>
13 <a href="https://docs.rs/wasm-bindgen"><img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /></a>
14 </p>
15
16 <h3>
17 <a href="https://rustwasm.github.io/docs/wasm-bindgen/">Guide</a>
18 <span> | </span>
19 <a href="https://docs.rs/wasm-bindgen">API Docs</a>
20 <span> | </span>
21 <a href="https://github.com/rustwasm/wasm-bindgen/blob/master/CONTRIBUTING.md">Contributing</a>
22 <span> | </span>
23 <a href="https://discord.gg/xMZ7CCY">Chat</a>
24 </h3>
25
26 <sub>Built with ���� by <a href="https://rustwasm.github.io/">The Rust and WebAssembly Working Group</a></sub>
27</div>
28
29## Example
30
31Import JavaScript things into Rust and export Rust things to JavaScript.
32
33```rust
34use wasm_bindgen::prelude::*;
35
36// Import the `window.alert` function from the Web.
37#[wasm_bindgen]
38extern "C" {
39 fn alert(s: &str);
40}
41
42// Export a `greet` function from Rust to JavaScript, that alerts a
43// hello message.
44#[wasm_bindgen]
45pub fn greet(name: &str) {
46 alert(&format!("Hello, {}!", name));
47}
48```
49
50Use exported Rust things from JavaScript with ECMAScript modules!
51
52```js
53import { greet } from "./hello_world";
54
55greet("World!");
56```
57
58## Features
59
60* **Lightweight.** Only pay for what you use. `wasm-bindgen` only generates
61 bindings and glue for the JavaScript imports you actually use and Rust
62 functionality that you export. For example, importing and using the
63 `document.querySelector` method doesn't cause `Node.prototype.appendChild` or
64 `window.alert` to be included in the bindings as well.
65
66* **ECMAScript modules.** Just import WebAssembly modules the same way you would
67 import JavaScript modules. Future compatible with [WebAssembly modules and
68 ECMAScript modules integration][wasm-es-modules].
69
70* **Designed with the ["Web IDL bindings" proposal][webidl-bindings] in mind.**
71 Eventually, there won't be any JavaScript shims between Rust-generated wasm
72 functions and native DOM methods. Because the wasm functions are statically
73 type checked, some of those native methods' dynamic type checks should become
74 unnecessary, promising to unlock even-faster-than-JavaScript DOM access.
75
76[wasm-es-modules]: https://github.com/WebAssembly/esm-integration
77[webidl-bindings]: https://github.com/WebAssembly/proposals/issues/8
78
79## Guide
80
81[**�� Read the `wasm-bindgen` guide here! ��**](https://rustwasm.github.io/docs/wasm-bindgen/)
82
83You can find general documentation about using Rust and WebAssembly together
84[here](https://rustwasm.github.io/docs).
85
86## API Docs
87
88- [wasm-bindgen](https://docs.rs/wasm-bindgen)
89- [js-sys](https://docs.rs/js-sys)
90- [web-sys](https://docs.rs/web-sys)
91- [wasm-bindgen-futures](https://docs.rs/wasm-bindgen-futures)
92
93## License
94
95This project is licensed under either of
96
97 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
98 http://www.apache.org/licenses/LICENSE-2.0)
99 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
100 http://opensource.org/licenses/MIT)
101
102at your option.
103
104## Contribution
105
106**[See the "Contributing" section of the guide for information on
107hacking on `wasm-bindgen`!][contributing]**
108
109Unless you explicitly state otherwise, any contribution intentionally submitted
110for inclusion in this project by you, as defined in the Apache-2.0 license,
111shall be dual licensed as above, without any additional terms or conditions.
112
113[contributing]: https://rustwasm.github.io/docs/wasm-bindgen/contributing/index.html
