WebAssembly (WASM) Build
========================

{{#include ../../links.md}}

```admonish question.side.wide "But why?"

There is already a fast and powerful scripting language that integrates nicely with WASM – **JavaScript**.

Anyhow, do it because you _can_!
```

It is possible to use Rhai when compiling to WebAssembly (WASM).

This yields a scripting engine (and language) that can be run in a standard web browser,
among other places.

```admonish warning "Unavailable features"

When building for WASM, certain features will not be available,
such as the script file APIs and loading [modules] from external script files.
```

```admonish example "Sample"

Check out the [_Online Playground_]({{rootUrl}}/tools/playground.md) project which is driven
by a Rhai [`Engine`] compiled into WASM.
```


JavaScript Interop
------------------

Specify either of the [`wasm-bindgen`] or [`stdweb`] features when building for WASM that requires
interop with JavaScript. This selects the appropriate JavaScript interop layer to use.

It is still possible to compile for WASM without either [`wasm-bindgen`] or [`stdweb`],
but then the interop code must then be explicitly provided.


Target Environments
-------------------

~~~admonish abstract "WASI: `wasm32-wasi`"

There is no particular setting to tweak when building for WASI.
~~~

~~~admonish abstract "JavaScript: `wasm32-unknown-unknown` + `wasm-bindgen`/`stdweb`"

Rhai requires a system-provided source of random numbers (for hashing).

Such random number source is available from JavaScript (implied by `wasm-bindgen` or `stdweb`).

The `js` feature on the [`getrandom`](https://crates.io/crates/getrandom) crate is
enabled automatically to provide the random  number source.
See also: <https://docs.rs/getrandom/latest/getrandom/#webassembly-support> for details.
~~~

~~~admonish warning "Raw: `wasm32-unknown-unknown`"

Rhai requires a system-provided source of random numbers (for hashing).

Non-JavaScript/non-browser environments may not have random numbers available, so it is necessary to
opt out of `default-features` in order to enable [static hashing] which uses fixed (non-random) keys.

```toml
[dependencies]
rhai = { version = "{{version}}", default-features = false, features = [ "std" ] }
```
~~~


Size
----

Also look into [minimal builds] to reduce generated WASM size.

A typical, full-featured Rhai scripting engine compiles to a single WASM32 file that is less than
400KB (non-gzipped).

When excluding features that are marginal in WASM environment, the gzipped payload can be shrunk further.

Standard [packages][built-in packages] can also be excluded to yield additional size savings.


Speed
-----

In benchmark tests, a WASM build runs scripts roughly 30% slower than a native optimized release build.


Common Features
---------------

Some Rhai functionalities are not necessary in a WASM environment, so the following features
are typically used for a WASM build:

|            Feature             | Description                                                                                                                                                                                                                           |
| :----------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`wasm-bindgen`] or [`stdweb`] | use [`wasm-bindgen`](https://crates.io/crates/wasm-bindgen) or [`stdweb`](https://crates.io/crates/stdweb) as the JavaScript interop layer, omit if using custom interop code                                                         |
|         [`unchecked`]          | when a WASM module panics, it doesn't crash the entire web app; however this also disables [maximum number of operations] and [progress] tracking so a script can still run indefinitely &ndash; the web app must terminate it itself |
|          [`only_i32`]          | WASM supports 32-bit and 64-bit integers, but most scripts will only need 32-bit                                                                                                                                                      |
|         [`f32_float`]          | WASM supports 32-bit single-precision and 64-bit double-precision floating-point numbers, but single-precision is usually fine for most uses                                                                                          |
|         [`no_module`]          | a WASM module cannot load modules from the file system, so usually this is not needed, but the savings are minimal; alternatively, a custom [module resolver] can be provided that loads other Rhai scripts                           |
|      [`no_custom_syntax`]      | if [custom syntax] is not used, this results in a small size saving                                                                                                                                                                   |

The following features are typically _not_ used because they don't make sense in a WASM build:

|    Feature    | Why unnecessary                                                                                       |
| :-----------: | ----------------------------------------------------------------------------------------------------- |
|   [`sync`]    | WASM is single-threaded                                                                               |
|  [`no_std`]   | `std` lib works fine with WASM                                                                        |
| [`metadata`]  | WASM usually doesn't need access to Rhai functions metadata                                           |
| [`internals`] | WASM usually doesn't need to access Rhai internal data structures, unless you are walking the [`AST`] |
| [`debugging`] | unless debugging is needed                                                                            |