| 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://github.com/rustwasm/wasm-bindgen/actions/workflows/main.yml?query=branch%3Amain"><img src="https://github.com/rustwasm/wasm-bindgen/actions/workflows/main.yml/badge.svg?branch=main" 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/wasm-bindgen/">Guide (main branch)</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 |
## Install `wasm-bindgen-cli` |
| 30 |
|
| 31 |
You can install it using `cargo install`: |
| 32 |
|
| 33 |
``` |
| 34 |
cargo install wasm-bindgen-cli |
| 35 |
``` |
| 36 |
|
| 37 |
Or, you can download it from the |
| 38 |
[release page](https://github.com/rustwasm/wasm-bindgen/releases). |
| 39 |
|
| 40 |
If you have [`cargo-binstall`](https://crates.io/crates/cargo-binstall) installed, |
| 41 |
then you can install the pre-built artifacts by running: |
| 42 |
|
| 43 |
``` |
| 44 |
cargo binstall wasm-bindgen-cli |
| 45 |
``` |
| 46 |
|
| 47 |
## Example |
| 48 |
|
| 49 |
Import JavaScript things into Rust and export Rust things to JavaScript. |
| 50 |
|
| 51 |
```rust |
| 52 |
use wasm_bindgen::prelude::*; |
| 53 |
|
| 54 |
// Import the `window.alert` function from the Web. |
| 55 |
#[wasm_bindgen] |
| 56 |
extern "C" { |
| 57 |
fn alert(s: &str); |
| 58 |
} |
| 59 |
|
| 60 |
// Export a `greet` function from Rust to JavaScript, that alerts a |
| 61 |
// hello message. |
| 62 |
#[wasm_bindgen] |
| 63 |
pub fn greet(name: &str) { |
| 64 |
alert(&format!("Hello, {}!", name)); |
| 65 |
} |
| 66 |
``` |
| 67 |
|
| 68 |
Use exported Rust things from JavaScript with ECMAScript modules! |
| 69 |
|
| 70 |
```js |
| 71 |
import { greet } from "./hello_world"; |
| 72 |
|
| 73 |
greet("World!"); |
| 74 |
``` |
| 75 |
|
| 76 |
## Features |
| 77 |
|
| 78 |
* **Lightweight.** Only pay for what you use. `wasm-bindgen` only generates |
| 79 |
bindings and glue for the JavaScript imports you actually use and Rust |
| 80 |
functionality that you export. For example, importing and using the |
| 81 |
`document.querySelector` method doesn't cause `Node.prototype.appendChild` or |
| 82 |
`window.alert` to be included in the bindings as well. |
| 83 |
|
| 84 |
* **ECMAScript modules.** Just import WebAssembly modules the same way you would |
| 85 |
import JavaScript modules. Future compatible with [WebAssembly modules and |
| 86 |
ECMAScript modules integration][wasm-es-modules]. |
| 87 |
|
| 88 |
* **Designed with the ["Web IDL bindings" proposal][webidl-bindings] in mind.** |
| 89 |
Eventually, there won't be any JavaScript shims between Rust-generated wasm |
| 90 |
functions and native DOM methods. Because the wasm functions are statically |
| 91 |
type checked, some of those native methods' dynamic type checks should become |
| 92 |
unnecessary, promising to unlock even-faster-than-JavaScript DOM access. |
| 93 |
|
| 94 |
[wasm-es-modules]: https://github.com/WebAssembly/esm-integration |
| 95 |
[webidl-bindings]: https://github.com/WebAssembly/proposals/issues/8 |
| 96 |
|
| 97 |
## Guide |
| 98 |
|
| 99 |
[**📚 Read the `wasm-bindgen` guide here! 📚**](https://rustwasm.github.io/docs/wasm-bindgen/) |
| 100 |
|
| 101 |
You can find general documentation about using Rust and WebAssembly together |
| 102 |
[here](https://rustwasm.github.io/docs). |
| 103 |
|
| 104 |
## API Docs |
| 105 |
|
| 106 |
- [wasm-bindgen](https://docs.rs/wasm-bindgen) |
| 107 |
- [js-sys](https://docs.rs/js-sys) |
| 108 |
- [web-sys](https://docs.rs/web-sys) |
| 109 |
- [wasm-bindgen-futures](https://docs.rs/wasm-bindgen-futures) |
| 110 |
|
| 111 |
## License |
| 112 |
|
| 113 |
This project is licensed under either of |
| 114 |
|
| 115 |
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or |
| 116 |
http://www.apache.org/licenses/LICENSE-2.0) |
| 117 |
* MIT license ([LICENSE-MIT](LICENSE-MIT) or |
| 118 |
http://opensource.org/licenses/MIT) |
| 119 |
|
| 120 |
at your option. |
| 121 |
|
| 122 |
## Contribution |
| 123 |
|
| 124 |
**[See the "Contributing" section of the guide for information on |
| 125 |
hacking on `wasm-bindgen`!][contributing]** |
| 126 |
|
| 127 |
Unless you explicitly state otherwise, any contribution intentionally submitted |
| 128 |
for inclusion in this project by you, as defined in the Apache-2.0 license, |
| 129 |
shall be dual licensed as above, without any additional terms or conditions. |
| 130 |
|
| 131 |
[contributing]: https://rustwasm.github.io/docs/wasm-bindgen/contributing/index.html |